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“production level” code is 
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a major “black hole”. , 
Be sure to ask about our 


OS/2 Enterprise Workgroup 
for extra savings. 


VERITAS VISTA, VistaSIM, VistaGRAPH and VistaTEST are trademarks of VERITAS Soltware. 
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POINT-AND-CLICK TIES GUI FIELDS TO DATA OBJECT TECHNOLOGY 





Automatically connect GUI fields to your database, and you have a With TechBridge Builder you get a complete set of classes, the 
form that can view and update data. Or import table definitions and let —_ practical building blocks that you can tailor to build your 

us auto-design a quick form for you to do query or present the data in application. Supporting these classes is a framework with over 
3-D business charts. Access DB2/2 and the whole DB2 family 700 base classes and 24,000 methods - a knowledge base of 
through DDCS/2; or Oracle 7 or 50 more data sources through technology like CUA '91, SQL, PM, and human factors. Don't 


EDA/SQL middleware. With TechBridge Builder you can do all this, waste time crafting your own framework, build on ours and 
with just drag-and-drop, point-and-click and absolutely NO CODING — jumpright into building applications that meet your specific 
because so much is AUTOMATED. needs. 





VISUAL DEVELOPMENT ON YOUR SYSTEM 


Place a pre-defined control group from your reuse library and attach The minimum system requirement is an 8M OS/2 machine with 
business logic or context sensitive help. Double-click to preview. 10M of free disk space. It's LAN enabled. 

Design a modal dialog or an advanced OOU! workplace with point- 
and-click. Use drag-and-drop to tie your objects together into an 
application, then let our packager produce the executables for you. 





SCRIPTING 





Double click on a form control and enter an event driven script, e.g. 
Multiply Principle by Interest giving Amount. Yes, it's just COBOL. 
Click to compile it. Click again to test it. Click to invoke the debugger. 
Iterative rapid development? You bet! 





TechBridge 
Technology Corp. 





1-800-463-8998 © 


TechBridge Technology Corp. 5001 Yonge St., Suite 1301, North York, Ontario, Canada M2N 6P6 Phone: (416) 222-8998 Fax: (416) 222-0168 
Prices and specification are subject to change without notice. Price does not include freight and taxes where applicable. Prices quoted in US dollars. TechBridge, TechBridge Technology and TechBridge Builder 
are registered trademarks of TechBridge Technology Corp. ©1994 TechBridge Technology Corp, All other brand and product names are trademarks or registered trademarks of their respective companies. 
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With so many advanced features 
in Micro Focus COBOL, there’s 





one you may have overlooked. 


The Future. 


At Micro Focus, we have a history of ensuring 
a bright future for our customers. 

Fifteen years ago, when the “future” was per- 
sonal computers, we brought the first true business 
application development environment to the desk- 
top. Over the years, we built on that foundation by 
providing the tools and utilities that delivered new 
levels of productivity to programmers. 

Today, we're ready for the next step: 
Introducing Object COBOL—the first true object 
oriented business programming environment. 

The Micro Focus Object COBOL Option pro- 
vides all the functionality you would expect from 
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Micro Focus is a registered trademark of Micro Focus Led. Object COBOL is a trademark of Micro Focus 


an object-oriented development environment— 
including encapsulation, polymorphism and 
inheritance. It also brings all the benefits of object 
orientation—reusability, real-world modeling and 
increased maintainability—to COBOL program- 
mers without discarding existing investments in 
code and skills. 

Object COBOL is shipped with a library of 
classes for managing collections of objects and 
for creating Graphical User Interfaces. These 
classes can be accessed and extended with 
another Object COBOL component, the Browser. 

Object COBOL even extends the COBOL 
language by letting you define syntax that best 


suits your business needs. Object COBOL’s 
unique vocabularies make applications easier to 
read, write and understand... for programmers 
and end-users alike! 

And the best part? It’s designed for COBOL 
programmers, so with Micro Focus, if you know 
COBOL, you're ready for an object-oriented 
future today. 

For the latest update on this new technology, 
call 800-MF-COBOL and ask for our white paper: 
The Object Oriented COBOL Model. 

Micro Focus: The past, present, and future of 
programming. 
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Gammatech REXX 
SuperSet /2 
by Softouch Systems 


The Superset/2 gives REXX the power of C by 
providing interfaces to LAN Server, NetBIOs, 
TCP/IP and Communications Manager/2, and 
by providing access to low level system facilities. 
including processes, threads, semaphores, 
Mames pipes. and VIO commands. The 
SuperSet/2 complements visual REXX program- 
ming packages. The 600+ page manual fully documents over 300 
functions in 7 DLLs ready to supercharge your REXX! 


List: $80 Ours: $69 FAXcetera #: 3621-0002 
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Visual SlickEdit” for OS/2 
by MicroEdge 

The same great programmers’ editor that 
gave you extensive language support, project 
Management, and superb editing features is 
now available on OS/2! Users of Visual 
SlickEdit for Windows or NT don't have to 
rewrite their macros when switching to 
OS/2. Macro source, dialog templates, and 
bitmaps are binary-compatible with Visual 
SlickEdit on all other platforms. 30 day 
risk-free trial! 


List: $295 Ours: $199 FAXcetera #: 1997-0002 
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IBM® OS/2° Warp v3 
by IBM 


OS/2 Warp Version 3, the reliable 32-bit 
operating system. makes computing easier. 
Features include a launch pad for easy access 
to your frequently used applications, built-in 
multimedia support, 3D animated icons and 
one-button install. Every copy includes a 
BonusPak for no extra charge. This BonusPak 
provides you with a complete set of tools for accessing and navigating 
the Internet; IBM Works—a suite of 32-bit applications; FaxWorks for 
(0S/2; HyperACCESS Lite; IBM Person to Person*: and much more. 
Systems with 4MB of memory are now supported. 


List: $129 Ours: $79 FAXcetera #: 3142-0035 
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OS/2 Warp 
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EZRAID 05/7 DISH MANAGEMENT SOFTWARE 
by PRO Engineering, Inc. 

EZRAID PRO is the OS/2 software solution 
that provides the same full powered RAID 
benefits found in hardware systems world- 
wide. With its unique technology, EZRAID 
PRO increases system performance, simplifies 
data management and ensures complete fault 
tolerance. EZRAID PRO supports spanning, 
RAID levels 0, 1, 4 and 5; is compatible with 
SCSI, IDE and ESDI; and is Ready for Warp 
and LAN Server 4.0. 


Lite 
PRO 
FAX cetera #: 


List: $5195 
List: $795 
1016-5101 


Ours: $764 
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RimStar” Programmer's Editor 
by RimStar Sey Inc. 


Features: 32-bit GUI, Syntax Coloring, 

ANSI *C" macro language, “C” Source 

Browser, unlimited redo/undo, no lim- 

its on number of files, windows, or line 

length. Emulates BRIEF plus many 

other editors. Compile/jump to error, 

hex editing, smart indenting, book- 

— + marks, completely configurable key- 

board mappings. WF/2 enabled and much more. Window & NT 
version available. 


List: $299 Ours: $259 FAXcetera #: 1013-0901 
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The Object Factory—IDL 
by Synaptec, Inc. 

IDL development environment for OS/2 De 
SOM. Includes multiple inheritance, 

framework filters, Drag drop backup > 

and restore, a SOM class browser, on- taal 

line help and much more. Use class develop- At 
ment notebooks to create new classes just by 

dropping them on the class browser. Eliminate the complexities of 
SOM programming. Framework filters focus development providing 
quicker access to the hundreds of SOM classes. View every inherited 
method from every parent in one list box. Manage class development 
with great ease and little effort. 


List: $250 Ours: $229 FAXcetera #: 1012-5402 
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c-tree Plus” 

by FairCom 

DOS * WINDOWS « NT * UNIX * OS/2 « SUN * 

RS6000 « HP9O00 *« MAC » QNX « BANYAN * 

SCO. This well known, highly portable data 

management package has become established 

: as the tool of choice for commercial develop- 

FAIR COM ment. Offering unprecedented data control, 
choose from direct low level access, ISAM level, 


or SQL access with the FairCom Server. Single User, MultiUser, or 
optional Client/Server, ANSI Standard. Full Source. No Royalties. 


List: $595 Ours: $495 FAXceten #: 1381-0004 
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EDITORIAL ARTIST 
Peter Altenberg 


Vice PRESIDENT/ 
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Regina Starr Ridley hat happened to 1994? It’s hard to be- 


lieve that another year is already start- 

ing. This is an appropriate time to wel- 

come two new additions to OS/2 Developer: 
Peter Westerman and Guy Scharf. 

Peter is our new Publisher, replacing the irre- 

placeable Cathy Passage. Peter comes to us from 


PUBLISHER 
Peter Westerman 


ADVERTISING SALES 


Yvonne Labat 
(415) 905-2353 


an wee Microsoft Systems Journal, of all places, where he 
oy ele will still maintain the duties of publisher. Mathe- 
Kristin Morgan matica completes his triad of magazines. Welcome 
(212) 626-2498 to. the other side, Peter! 

Marxetinc MANAGER Guy is another welcome addition to our pages. 


We have been without a software tools reviewer; 
now that slot is filled. Guy is no stranger to OS/2 
programming. He’s the sysop of the OS/2 Ven- 
dor and OS/2 Shareware forums on CompuServe. 


Susan McDonald 


Art Dinector/MARKETING 
Christopher H. Clarke 














Editors 
“Comments 





More Talent, Tools, and Tips 


OS/2 application development. If you have a 
favorite tool to recommend, or one that yeu just 
want to know more about, let Guy know. 


RACY PICTURES 

The second annual OS/2 Developer 
5K Race took place during Software 
Development ‘95 East. Those of you 
who participated were treated to an 
invigorating, early morning tour of 
our nation’s capital. If you didn’t stop 
to sightsee along the route, you just 
may have been a winner. 
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Dick Conklin 


TALK TO US! 
In 1995, as in 1994, we are striving to make OS/2 


MARKETING ASSISTANT He is also the cofounder, treasurer, and newsletter | Developer a publication that works for you. We 
fates Ditton editor for the OS/2 Bay Area Users Group. Guy have made some changes and plan to make more, 
will be reviewing the latest and greatest tools for but you are in the driver's seat. What kind of arti- 
ADVERTISING PRODUCTION cles do you like most? Are you seeking more 
COORDINATOR examples, tips, and hints? Are the code listings 
Glenn Sadin helpful? Do you use the sample program files in 
CincuLATION DirECTOR our CompuServe OS2DF2 forum? Have we over- 
John Rockwell looked any topics? Are we overdoing any? Take 
a moment and e-mail us with your comments; we 

CIRCULATION MANAGER 


want to hear from you! 
Lucinda Formyduval 
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Quantities are limited. 
Order now! 

For fastest service, 
fax your order to us 


at 415-905-496. 





: ki YES! Please send me copies of Smalltalk! 


Each copy is only $9.95 in the US or $12.95 in Canada. 
Please add $2.50 for shipping and handling. 


Pt 2 : Mail: Smalltalk 
J My check is enclosed > CO. Box 7046 


J Charge my credit card: (J Visa J MasterCard (J American San Francisco 


Express CA 94120 
Name Phone: 1-800-444-488 | 
Signature —_ Fax: (415) 905-4967 
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Now Master It at 
OS/2 DEVELOPMENT ’95 


Introducing the conference for advanced software development. 





= he publishers of OS/2 


la vi Developer magazine have 


assembled industry leaders to host the first 





independent Pan-European conference on 
OS/2. You'll sharpen your OS/2 skills 
and learn trom the experts about the latest 
techniques and technologies to increase 


your effectiveness on the job. 
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Our new OS/2 Toolbox column will review products that help develop applications for the OS/2 platform. 
By GUY SCHARF 


Product Reviewed: 
VX-REXX Client / 


Server Edition 


Guy Scharf 








elcome to the OS/2 Tool- 
box. In this column, I will 
be reviewing tools for the 


professional OS/2 developer. I am espe- 
cially interested in products that help in 
developing high-quality Presentation 
Manager applications. I’ll tell you what I 
see as the strong points of each tool as 
well as point out the limits of applicabil- 
ity and any major warts. 


VX-REXX 

VX-REXX for OS/2 is a powerful yet 
easy-to-use visual application develop- 
ment tool that uses REXX as its pro- 
gramming language. Watcom has just 
released VX-REXX for OS/2 Version 2.1 
and a new product named VX-REXX for 
OS/2 Client/Server Edition. The 
Client/Server Edition is version 2.1 with 
database and charting functions added. 
I tested the Client/Server Edition and 
found it a pleasure to use. 

VX-REXX helps you create native 
OS/2 Presentation Manager applica- 
tions. The integrated development envi- 
ronment includes a debugger, graphical 
design tools, and drag-and-drop pro- 
gramming. VX-REXX supports OS/2 
Presentation Manager controls, includ- 
ing the spin button, container, notebook, 
value set, and slider. VX-REXX adds pic- 
ture radio and push-button controls. 


Timer and DDEClient objects support 
timer events and building a DDE client 
application. 

When you are creating an applica- 
tion, VX-REXX is in design mode. After 
you have completed the application, you 
may run it directly, without leaving the 
development environment, in either a 
run mode or a debug mode. Debug mode 
runs your program under an integrated, 
easy-to-use debugger. Once you are satis- 
fied with the application, you can gener- 
ate an executable file for distribution. 

An application in VX-REXX is 
known as a project. To build the user in- 
terface, you place objects on the win- 
dows. An object consists of properties 
and methods. An object’s properties in- 
clude data and style settings. Methods 
are the functions the object can perform. 
For example, an entry field object has 
properties such as its value, maximum 
number of characters, color, and 
whether or not the field is readable. It 
has methods for setting the focus, get- 
ting and setting properties, and invok- 
ing help. To set the properties, you open 
the object’s Properties notebook and set 
as desired. You can also set properties at 
run time by calling methods to set the 
properties dynamically. You can even 
create the objects at run time rather than 
at design time. 


OS/2 DEVELOPER 


Like Presentation Manager, a VX- 
REXX application is event driven. Each 
object has a set of events it can respond 
to, such as a mouse click, entering data 
in the object, or another object being 
dropped on it. Most of the WM_CONTROL no- 
tification messages familiar to the 
Presentation Manager programmer 
show up as events. VX-REXX adds more 
events, including ones for drag-and- 
drop support and data verification. You 
define how the object is to respond to 
each event by coding an event handling 
routine. Select an event from a cascaded 
pop-up menu or from the properties 
notebook, and a section editor displays 
an edit window for your program to 
handle the event. The programming for 


Figure 1. Event list for a push button. 
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handling an event is often quite short. 
REXX is an easy language to use, and 
VX-REXX takes care of the details. 
Coding event handling routines is much 
easier in VX-REXX than in C. 

Multithreading is the key to OS/2 
applications that are responsive to the 
user. VX-REXX makes multithreading 
easy—one command launches a thread. 
The thread resides in a separate code file 
and can post results back to the 
launcher. 

Figure 1 shows the event list for the 
Cancel push button on a simple win- 
dow. Clicking the right mouse button on 
any object pops up a context menu. The 
Events menu item cascades to a list of all 
events supported for that control. A 
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check mark is placed beside events 
for which you have defined an 
event processing routine. 

Figure 2 shows part of the 
event routine for a Change event 
on an entry field. I wanted to dis- 
able the OK button if nothing had 
been entered in the entry field. 
Drag-and-drop programming 
makes this easy. If you drag an ob- 
ject to the edit window, a list of all 
methods and functions for that ob- 
ject is shown. Select the function to 
enable or disable an object and a 
dialogue appears allowing you to 
specify whether the object is to be 
enabled or disabled. The correct 
code is inserted in the edit window 
where you dropped the object. 

If you forget some REXX syn- 





"Line: $2 
value = VRGet({ "EF CUSTNAME”", "Value" | 
if value = "" then do 

ok = ¥YRSet{ "PB_OK", “Enabled”, 0 j 
enc 
elge do 

f 


3 ant 


Col: 1 


tax or a VX-REXX function, just 
click on the right mouse button in 
the edit window, select “insert 
code...”, and a list of VX-REXX 
functions as well as those of the 
REXX language itself is displayed. 
Select the one you want and the 
editor will insert the accurate and 
complete REXX statement. It’s 
hard to go wrong! 

The drag-and-drop program- 
ming and code insertion list 
greatly simplify learning the prod- 
uct. The implementation is very 
smooth and allows you to use as 
much or as little of it as you like. 
You can rely on it for everything, 
for nothing, or for anything in be- 
tween, depending on how adept 
you are with VX-REXX. 


Insert 


Figure 2. Enabling a push button using drag-and-drop programming. 
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Version 2.1 fills in many gaps 
found in earlier versions. Here are 
a few samples from a list too long 
to include in this review. In version 
2.1, you can drag an object from 
the toolbox to the window to cre- 
ate a new object of that type. Only 
one step (drag) is required rather 
than the two steps (select tool, cre- 
ate object) required in earlier ver- 
sions. A Tab Editor eases changing 
the tab order of objects in a win- 
dow. Properties have been added 
to many objects to support most 
Presentation Manager control 
styles. Many new methods and 
properties have been added to the 
Container and MLE objects. Drag- 
and-drop events are supported on 
all objects, making it easy to sup- 
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port dragging and dropping 
within an application. 

If you need to handle events 
VX-REXX does not support, the 
new DefineEvent method allows you 
to define a processing event for any 
Presentation Manager message. 
This is useful for handling unfore- 
seen conditions or custom objects 
with their own private messages. 


VX-REXX FOR 0S/2 

CLIENT/SERVER EDITION 

The VX-REXX for OS/2 Client/ 
Server Edition adds database and 
charting tools to VX-REXX version 
2.1. The database tools include two 
new objects—a connection object 
and a query object—and a 
Database Administrator utility. 
The charting tool is a new chart ob- 
ject that supports a wide range of 
chart types. Complete online and 
printed manuals and sample pro- 
grams demonstrate the varied ca- 
pabilities of these objects. 

The Client/Server Edition sup- 
ports IBM Database 2/2 (DB2/2), 
IBM DB2 on larger systems using 
DDCS/2, Watcom SQL for OS/2, 
and any ODBC-compliant data- 
base. For ODBC, you must obtain 
the ODBC driver for the database 
from InterSolv. 

But, wait! This is the Client/ 
Server Edition. Where is the Server 
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part of the product? Despite the 
name, there is neither a VX-REXX 
server component nor support for 
building a VX-REXX server. VX- 
REXX for OS/2 Client/Server edi- 
tion is a tool to build client appli- 
cations. Any server component is 
supplied by the database system. 

I tested VX-REXX for OS/2 
Client/Server Edition using IBM 
DB2/2 and both stand-alone and 
server versions of Watcom SOL for 
OS/2. 


EASE OF USE 

How easy is the database object to 
use? One way to measure that is to 
build an application that will view, 
search, and update a simple data- 
base table. To build that application 
in VX-REXX Client Server Edition, 
you open the Projects folder, tear off 
a new project from the project tem- 
plate, open your new project, and 
open the VX-REXX object within it. 
VX-REXX presents you with an 
empty window. Drag a connection 
object to the window. Open the con- 
nection object and enter the data- 
base name and type (IBM DB2/2, 
Watcom SQL, or ODBC). Close the 
connection object and drag a query 
object to the window. Open the 
query object and select the table 
and columns desired. Check the 
check boxes that ask VX-REXX to 
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Figure 3. Simple database table query and update application. 
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create the fields and push buttons. 
Check a radio button to indicate 
whether you want an entry field 
per column or prefer that multiple 
records be displayed in a container. 
Close the query object, and VX- 
REXX creates all of the fields and 
push buttons needed. 

You now have a working ap- 
plication, and it has taken only a 
few minutes. A few more minutes 
takes care of cosmetics, such as 
adding a title bar, changing field 
captions from database field names 
to user terms, and refining the lay- 
out by adjusting entry field lengths 
and rearranging the push buttons. 
Figure 3 shows the result. 

The sample programs include 
more complex examples, including 
two with master-detail organization. 

Simple methods to insert and 
delete records make database pro- 
gramming easy. If you want to use 
SOL directly, just ask the connection 
object to execute the SQL statement. 
The connection object provides 
error codes and messages from the 
SQL statement. Converting from 
DB2/2 to Watcom SQL is easy with 
the connection object. All you have 
to do is change the database type 
and name properties. That can be 
done either at design time or dur- 
ing execution. 

The new chart object packs a 
lot of functionality into one object. 
You can create the basic bar, area, 
pie, ribbon, and line charts. If you 
need something different, try the 
gantt, stock, box whisker, radar, 
100% area, XY, proportional, bub- 
ble, or combination charts. Some of 
the charts can be displayed three 
dimensionally. More than 150 chart 
options give you detailed control 
over the appearance of the chart. A 
Chart Editor lets you control these 
options at design time. As with 
other VX-REXX objects, you can 
also create charts or change these 
options at run time. 

The chart object has events for 
clicking and double clicking. When 
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Grading System by Subject 


Figure 4. Pie chart in three dimensions. 


you receive such a mouse event, 
you can ask which row and col- 
umn was clicked on. This makes it 
easy to implement a “drill-down” 
chart, where clicking on one part 
of the chart will explode the chart 
into more detail. The chart object 
can also be bound to a query ob- 
ject. This gives you a chart display 
of data from a database with al- 
most no programming required. 

Eleven sample chart programs 
are supplied, including two in 
which the chart is bound to a 
query object and one that demon- 
strates a drill-down application. 
Figure 4 shows a three-dimen- 
sional pie chart that is typical of 
the charts you can produce with 
the chart object. 


DOCUMENTATION 

The Client/Server edition includes 
two books: the Programmer's Guide 
and Reference and the Client/Server 
Edition Objects Guide. The first 
book is common to both VX-REXX 
2.1 and the Client/Server edition. 
The Programmer’s Guide includes a 
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tutorial on creating a simple appli- 
cation. It describes the structure of 
a VX-REXX project and has sec- 
tions addressing common pro- 
gramming topics, such as using 
multiple threads, modeless win- 
dows, debugging, controlling, 
other processes, and creating ob- 
jects at run time. 

The reference section lacks the 
detailed descriptions found in the 
version 2.0 manuals. With this new 
version, Watcom has reduced a 
450-page reference to a 25-page al- 
phabetical list of objects, proper- 
ties, events, methods, predefined 
routines, and functions. While 
everything in the books is avail- 
able online in an .INF file, I find it 
impossible to really learn a tool 
from online documentation. To be- 
come expert, I find I have to read 
reference manuals from cover to 
cover until I understand it all. You 
won’‘t want to discard your old 
VX-REXX 2.0 manual! 

The Client/Server Edition Ob- 
jects Guide contains two sections 
describing the features of the VX- 
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REXX Client/Server Edition be- 
yond those included in the base 
VX-REXX version 2.1: the Database 
Objects Guide and the Chart 
Object Guide. Each guide has tuto- 
rial, programmer's guide, and ref- 
erence sections. In this book, the 
reference sections include com- 
plete descriptions and not just lists. 

All of the books are available 
online as .INF files that use hyper- 
links well. The information is orga- 
nized in additional ways to the 
printed presentation. For example, 
the online reference shows the 
events, properties, and methods 
available for each type of object. 
The online documents are a plea- 
sure to use. 


WARTS AND BLEMISHES 

The base components of VX-REXX 
2.1 have been honed over several 
releases and operate very smooth- 
ly. The database tools of the 
Client/Server Edition are new and 
do have rough edges, primarily in 
the design environment. I was able 
to work around problem areas eas- 
ily though. The Database Admin- 
istrator tool is another story. It had 
serious enough flaws that | was 
unable to use it to define a data- 
base. Fortunately, this tool is a 
nicety and not essential. 

Watcom released a version 2.1a 
patch after this review was com- 
pleted. This patch corrects prob- 
lems in version 2.1 and problems 
related to OS/2 Warp 3. I checked 
the problems I had found, and they 
were corrected. The 2.la patch is 
available in the Watcom forum on 
CompuServe. 


LIMITS OF APPLICABILITY 

While VX-REXX does provide a 
Presentation Manager printer se- 
lection dialogue to make selecting 
the printer easy, Presentation 
Manager printing is not provided. 
To print, you write a report to a 
file, including printer-specific con- 
trol codes if desired, then print the 


file using a VRPrintFile function. 
The chart object includes a method 
to print a chart, but VX-REXX does 
not provide a way to combine a 
chart with other printed output. 
VX-REXX provides an un- 
adorned entry field. More complex 
entry fields for dates, zip codes, 
and other formats are available 
from third-party vendors as add-on 
components. Watcom also has an 
Object Development Kit available 
so you can develop your own cus- 
tom objects to use in VX-REXX pro- 
jects. VX-REXX does not support 
drawing directly on a window; you 
would need to develop your own 
object to access a window directly. 
Also, VX-REXX does not support 
every last feature of OS/2 
Presentation Manager, such as the 
owner draw style. The ease of use 
and rapid development more than 
made up for any small features that 
were missing in my use. In writing 
a small business application, VX- 
REXX supported all of the OS/2 
Presentation Manager features | 
needed and many more besides. 
REXX is not C, and with this 
distinction come both advantages 
and disadvantages. It may be diffi- 
cult to work with some data types 
and structures, as REXX has only 
strings and integers. Using C and 
Presentation Manager, you can cre- 
ate subclasses and superclasses to 
alter the behavior of objects. This 
will be harder to do in REXX. An 
interpreted language such as REXX 
is likely to be slower than C in some 
situations, such as loading a con- 
tainer with thousands of records. 
Applications developed in VX- 
REXX can be distributed as EXE 
files. Some Watcom DLL files are 


required; they may be distributed 
without royalty payment. The 
VROBJ.DLL file has grown to 893K 
in this release; database and chart- 
ing DLLs and related files are 
about 200K and 350K, respectively, 
depending on the database to be 
supported. 


TECHNICAL SUPPORT 

Watcom offers technical support 
by telephone, fax, BBS, Internet, 
and CompuServe (GO WATCOM). 
A fax response system provides 
technical information. I called 
Watcom twice and found the staff 
to be courteous and knowledge- 
able. I was quickly passed on to a 
specialist for a more complex ques- 
tion. | posted several questions on 
the Watcom forum on Compu- 
Serve. How-to questions were gen- 
erally answered overnight; more 
difficult questions requiring re- 
search took longer. The Watcom 
staff was very receptive to problem 
reports and very honest about 
problems and workarounds. I 
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found this response refreshing; it 
gave me confidence that I would 
get real answers to my questions. 


SUMMARY 

VX-REXX is excellent for develop- 
ing OS/2 Presentation Manager 
applications quickly. The drag- 
and-drop programming interface 
makes learning VX-REXX and 
REXX easy. All OS/2 controls are 
supported, and custom controls 
can be added, allowing the devel- 
oper great flexibility in designing 
the application. The Client/Server 
Edition makes using an SQL data- 
base easy. I will definitely keep the 
VX-REXX Client/Server Edition in 
my toolbox. 


Guy Scharf /s president of Software 
Architects Inc., a software development 
firm specializing in developing 0S/2 
Presentation Manager applications for 
vendors and business. He can be reached 
via e-mail at 76702.557@compuserve.com 
or at Software Architects Inc., 2163 Jardin 
Drive, Mountain View, Calif. 94040. 
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Keeping with the theme of the issue, a mystical area of programming, the exception handler, is 
demystified. By MARK BENGE and MATT SMITH 


An Exception You 
Can Handle 





Mark Benge 





Matt Smith 


16 


ot so long ago, in a place 
nearby (hey, Star Wars is in 
production again, just getting 
ready, sort of), a demo was being 
waged. Wonderful screens of dialogues 
and windows were being dutifully dis- 
played to wonderment of all. Everyone 
was being mesmerized by this show of 
power and majesty. Splat! Wait a 
minute, that wasn’t part of the script. 

While looking for a quick exit from 
this major embarrassment, it was no- 
ticed that the audience was moving in 
closer, trying to get a look at the display. 
They were doing this while saying to 
each other that they had to know how it 
was done. 

Hold it, did they just ask how it 
went splat? Nope. They wanted to know 
how the exception handler was done 
such that the exception dialogue re- 
ported the function where the applica- 
tion tripped over itself. 
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GRACEFULLY EXITING STAGE LEFT 
Interesting, that. Having a major faux 
pas and being able to walk away virtu- 
ally unscathed. Why? Quite simply by 
having a graceful exception handler that 
told the user what was happening and 
providing us, the writers of the applica- 
tion, with a nice report of where things 
went wrong. 


Unfortunately, almost all the major 
compiler writers just don’t get it that 
OS/2 has a really neat exception han- 
dler that with a little thought could pro- 
duce useful diagnostic information and 
should be part of the compiler they sell. 

Now, you may be asking, why 
would we want to talk about it and not 
keep this as one of the trade secrets or 
crown jewels? We want to challenge 
those compiler writers into providing 
support for this issue. We will show you 
why in a moment. 


YUCKO, THEORY TIME 

Okay, kids, put on your theory propeller 
caps and follow the discussion on the 
chalkboard. The problem: OS/2 catches 
our program doing something stupid 
and tells our exception handler where it 
occurred, Great, let’s just print out the 
address and call it a day! 

Yeah, right. That’s exactly what 
most of the compiler exception handlers 
do if they handle the exception at all. We 
still don’t know where the program shot 
itself in the foot though. 

Well, maybe we should use Method I: 
the good ol’ linker map, which is the 
method that we have all used for years 
and years. Unfortunately, it really is 
only useful in telling us sort of, maybe, 
kind of, somewhat where the problem 
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occurred. This is due to the fact 
that the link map shows only the 
addresses for the global functions 
and not for any statics. It is also 
difficult to try to locate the prob- 
lem if the address is outside the 
main application address space, 
such as within a system call or 
within a DLL you have called. 

The method we will show, 
Method II, borrows heavily from 
the link map concept but without 
paperwork. Here we rely on tables 
of tables. Huh?? 

Okay, the concept is really 
quite simple; it is just the imple- 
mentation that gets a wee bit 
messy and tedious. Consider that 
the exception address is within 
your main application space. By 
main application space, we mean 
your source from the first module 
up to the last module, as illus- 
trated in Figure 1. Following this 


main 
U) Module 1 


Module ? 


Exception. 
Address 


last module usually is the start of 
the compiler run-time library. By 
rights, it is part of your address 
space, but since we don’t know its 
address or function address, we 
treat it as being outside our ad- 
dress space like that of the system. 

Each of your functions follow 
one another, maybe in the order you 
coded or in some other order the 
compiler and linker have put to- 
gether. The only thing we need to do 
is find out between which two func- 
tions the exception occurred. Then 
we know where we tripped up. 
That’s it. It is as simple as that. The 
idea even works with your DLLs. 

Method III is where the com- 
piler writers are needed and 
should take note. Using Method II, 
where the module and function are 
reported, you should also have the 
source line reported. Now that 
would be truly wonderful. 


Known 
Address 
space 


Module 3 


ExceptHandler( } 


Figure 1. Main application space. 
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ACTUAL DESIGN 

The real trick to making most of 
this work is the building of a table 
within each source module that 
records the function address along 
with the name of the function. Then 
in the exception handler of the ap- 
plication, a different table is built 
that references each of the tables 
within each of the different mod- 
ules. Like we said, tables of tables. 

When an exception occurs that 
is handled by our exception han- 
dler, we sort the tables so they are 
in ascending order and then walk 
them, trying to find the two func- 
tions in between which the excep- 
tion falls. Once found, we know 
exactly where we died. This works 
great, especially when you have 
your software being used halfway 
around the world and it can tell 
you exactly where it is feeling sick. 
Only if it were truly this simple! 

What do you do when there is 
the possibility of the exception oc- 
curring within a DLL? Well, first 
you check to see if the exception 
falls within your source code ad- 
dress space, namely from the start 
of the application to the exception 
handler, which we have caused to 
be at the end. If it isn’t in this 
space, we call the exception lookup 
handlers within each of our DLLs 
to see if the exception occurred in 
one of them. 

If none of them reports owning 
the naughty code, we then use our 
next death-defying act (at times, as 
we will show in a moment, this is 
exactly how we have coined it). 
Here we walk the stack with the 
idea that we will trace back 
through to our address space. 
Then we state that the function 
was the starting point of the stack 
trace. At least this gives us an idea 
of where to start looking. 

And, if all else fails, like when 
the stack is a mixture of 32-bit and 
16-bit addresses, we stick our 
heads in the sand just like the com- 
piler writers do. 


THE IMPLEMENTATION 

In the sample source code, which 
can be found lurking in the usual 
electronic hangouts, we have a 
bunch of modules with some stu- 
pid, do-nothing functions that, de- 
pending on the alignment of the 
planets, will decide to GP. 

Within each is a table that is 
declared statically. This table is 
then referenced by a structure, IN- 
TERNALADDRESS that contains the mod- 
ule name and the table address. 

Then, within the XCept.C mod- 
ule is an array of the INTERNALADDRESS 
structures from each of the mod- 
ules. This is the backbone of our 
lookup scheme. 

Inside our exception handler, 
we place the smarts to sort the ta- 
bles and call a routine that will do 
the actual lookup. If the address 
isn’t found within the lookup ta- 
bles or any DLL’s, we use the re- 
turned BP register to start the walk 
back through the stack. 

Now, this walk on the wild 
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Access violation occurred at CS:EIP = 0x005b:0x00011092 


side of the stack can be tricky. First, 
you have to be careful that the 
value you see is a 32-bit value and 
not a 16-bit return address. 

This is done by checking the 
address against the stack limit. If it 
is outside it, it is probably a 16-bit 
address. Next, and there is no 
check on this, if the compiler wee- 
nies have decided to party on the 
BP register by using it as a general- 
purpose register, you are most def- 
initely out of luck. Carefully check 
your compiler documentation 
since some of these compilers 
don’t explain very well in their 
documentation what happens 
when they use the BP register for 
anything but the stack frame. 

Once we have traced back into 
our address space through the 
stack, we are essentially done. We 
just have to look up the traced 
back address within our tables. 

Now, it is a matter of reporting 
the damage. Here we do it in two 
places: a log file that we append 


Invalid Write Access occurred at 0x0053:0x00000000 
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Figure 2. Exception dialogue. 


JANUARY/FEBRUARY 


‘995 


each time an exception occurs and 


the exception dialogue shown in 
Figure 2. 


A LATE CHRISTMAS PRESENT 

One of the really neat things about 
OS/2 is that if you provide the 
proper code, you can recover 
gracefully from a full-stop excep- 
tion and continue using your ap- 
plication. A good example would 
be a conversion filter. Here, you 
would design it so any memory 
being used is not intermixed with 
the main application. Therefore, if 
things decide to fall apart, your 
main data is still in one piece. 

The best way to do this is to 
place the filter within a dynami- 
cally loaded DLL. Just as soon as 
the function in the DLL is called, 
you register an exception handler 
within the DLL. This exception 
handler is now at the top of the 
chain, which means it gets called 
first. Next, you do a set jmp call, so if 
an exception occurs, you can 
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gracefully recover and report it to 
the user. 

The DLL exception handler in 
this case can be like the full-blown 
one. Instead of stating it is fatal, 
however, state it is recoverable. 
Then perform a longjmp back to the 
location where you did the set jmp 
and unwind the DLL exception 
handler before returning to the 
main application. 

We want to caution you here. 
You have to be careful with this and 
have clearly thought through your 
design of both the DLL and your 
data. You should really only use 
this if you can separate your appli- 
cation data from that of the DLL. 


MAKING IT ALL WORK 

To make this work with a much 
larger application, you must update 
the tables by hand each time you 
add or remove a function. This up- 
dating of the tables is why we men- 
tioned earlier the tedious nature of 
the exception handler. Hence our 
endearment with the compiler writ- 
ers. The compilers can easily and 
dynamically update these tables for 
us. They will ensure that they have 


all of the functions defined, 
whereas we may make a mistake if 
we are not diligent. 

The same problem occurs 
when we add a new module. We 
need to create a new entry within 
the internal address array after we 
have created the table within the 
new module. 

But this work will be worth it 
when you get your first support 
call from some pub in Edinburgh 
and you know exactly where to 
look within your application. 


Mark Benge, /BM Software Solutions, 
Cary, N.C., is a staff programmer who 
joined IBM in 1989 and has worked on 
various CUA ‘97 controls for OS/2 2.x. He 
works in IBM user interface class library 
development, where he was involved in 
the implementation of C++ classes for 
drag and drop in C Set++ 2.1. Mark has a 
B.S. in computer science from Western 
Carolina University. He can be reached on 
CompuServe at 73532,2063 and on 
Internet at banzai@vnet.ibm.com. 


Matt Smith, Prominare /nc., Toronto, 


Ont., is lead architect for the Prominare 
Development System, an OS/2 2.x 
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advanced GUI development environment. 
Matt has been actively involved with 
OS/2 since 1988 and cofounded 
Prominare in 1990. Smith has a degree in 
architecture from the University of 
Waterloo. He can be reached on Internet 
at msmith@interlog.com. 
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Often some of the simplest ideas yield the greatest benefits. This issue's Programming Insider shows 
you how aliasing functions can give your applications more speed in less space. By DAVID REICH 


An API by Any 
Other Name... 





Dawid Reich | 


~ his issue, | want to discuss an 
important but usually unknown 

or overlooked aspect of applica- 

tion performance tuning: the subject of 
calling APIs in DLLs, whether they be 
your own DLLs or system service DLLs. 
Depending on your intended use of 
functions that reside in DLLs, you have 
many options in how to call and use 
them. There are also obvious perfor- 
mance impacts if you call an API by 
name, having it preloaded and fixed up 
when you call the function, or if you 
load the module when you need it and 
fix up the reference at run time. There 
are also impacts in calling a single func- 
tion, or sets of functions, all over your 
code. Let's first look at how DLLs work. 


LINKING DYNAMICALLY 
Like static run-time libraries, a DLL is a 
library of functions that can be used by 
many programs. However, the functions 
in DLLs are not bound to executable 
programs. The functions remain in the 
DLLs, which are loaded by the OS/2 
program loader and are callable by pro- 
grams written to access their functions. 
A statically linked library is a .LIB 
file, bound to an executable. A DLL con- 
sists of the DLL, which contains the rou- 
tines, and a .LIB file, which is the “road 
map” to the DLL. When you build an 


application and link with a DLL's .LIB 
file, the linker places not the routine (as 
it would with a statically linked library) 
but an external reference record that 
points to the DLL and a function num- 
ber (the ordinal of the function) within 
the DLL into the object code. 

If you were to peek inside your exe- 
cutable program file, you would see that 
in the CALL instructions for all of the DLL 
reference records, there is just a refer- 
ence to an external function. More im- 
portantly, if you were to look at the EXE 
header (you can, with the tool EXEHDR, 
which is part of the compiler and 
toolkit), you would see there are refer- 
ences to DLLs and ordinals, such as 
PMWIN.139. This indicates that the function 
at ordinal 139 (the 139th function) in 
PMWIN.DLL is the one being referenced. 

This list of DLL ordinals or imports 
(referencing a DLL’s function by name is 
also called importing the function) in 
the EXE header is called the import list. 
Whenever an OS/2 program is loaded, 
the program loader examines the import 
list and fixes up the references to the 
DLLs. This causes the DLL to be loaded 
for the reference to be fixed up. This is 
not a terrible thing when calling system 
services since most of the system DLLs 
are already loaded. Also, the fix-up is 
much faster than if you were using 
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your own DLL since the loader 
would have to load and then re- 
solve these addresses. This de- 
scription applies when you import 
a function by name, such as calling 
WinCreateWindow or DosSleep. 

It is also possible to call func- 
tions in DLLs by address. After all, 
DLLs are shared code. Your pro- 
gram can gain addressability to the 
code in the DLL through importing 
by name or by calling DosLoadModule. 
Once you have a handle to a DLL 
module, you have addressability to 
the module. Simply stated, address- 
ability means that you can call a 
function in its address space with- 
out taking protection exceptions. 

When you call DosLoadModule, 
you are given a module handle. 
The other part to calling a DLL 
function is to get the address of the 
function you want. You do this by 
calling DosQueryProcAddr. This func- 
tion takes the DLL handle, the 
module name or ordinal, and gives 
you the 32-bit address of the func- 
tion you want. You can then call 
the function, as shown in Figure 1. 

You'll notice that the function 
call does not involve importing the 
function by name, and as such, 
there is no entry for the function in 
the EXE header. You may wonder 
where I’m heading with all this. 


FIXING UP AND ALIASES 

As you've just seen, whenever you 
call a function in a DLL by name, 
you import the name and it stays 
in the imports table in the EXE 
header. For every reference in the 
code to one of these imports, there 
is a fix-up in the application 
process’s swappable memory. Not 
only are fix-ups performed when 
the application loads, slowing ap- 
plication load performance, they 
are also stored in application- 


Figure 1. Calling a DLL function by address. 
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swappable memory, increasing the 
working set size of the application. 

You could eliminate the fix-ups 
in application-swappable memory 
by calling the functions by address, 
but that is a bit more inconvenient, 
both in the amount of code you 
have to write and in the inherent 
parameter checking you get when 
calling the APIs. (The compiler 
checks the code against the function 
prototypes to give you parameter 
checking, whereas when calling by 
function pointer, as in Figure 1, you 
get no parameter checking.) Aside 
from the inconvenience, you'll have 
DosLoadModule and DosQueryProcAddr 
calls in many places in the code 
where you would not otherwise, 
wiping out the memory savings 
you'd gain by calling by address. 

You can eliminate much of this 
overhead and keep the advantage 
of compile-time parameter check- 
ing with a simple technique I call 
“aliasing” APIs. That is, just call 
the API by another name. 

Let’s look at the difference be- 
tween a DLL function call, which 
we've been discussing, and a call 
to an internal function of the appli- 
cation. DLL function calls have ex- 
ternal reference records in the code 
of your application. In the 16-bit 
world, these would have been far 
calls. In the 32-bit world, these are 
simply near calls since the entire 
system is one 32-bit flat address 
space. An internal function call is 
also a near call. The biggest differ- 
ence, and the one in which we are 
interested for this discussion, is the 
overhead inside your application 
to store all of the fix-ups for exter- 
nal, or DLL, function calls. Internal 
function calls need no fix-ups. If 
you can call system services with 
internal function calls, you reduce 
the need for these fix-ups. 
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If you have many places in 
your application where you call, 
say, DosBeep, you will have a fix-up 
for every call. Why not just write 
one small function in your applica- 
tion, called MyDosBeep, which takes 
the same parameters as DosBeep? 
Inside MyDosBeep, you simply call the 
real system service DosBeep with the 
same parameters as DosBeep taken 
from the parameters passed to 
MyDosBeep. This may seem an inordi- 
nate amount of overhead to save a 
few bytes here and there, but de- 
pending on how often you use a 
system API, you can save a consid- 
erable amount of memory. 

This simple technique not only 
saves you memory when you need 
to call system services but also can 
help you structure your own code 
to make it easier to maintain and 
enhance, For example, writing 
your own “wrapper” functions to 
encapsulate calls to the OS/2 
memory management APIs allows 
you to track the memory function 
calls in your application better. 
Rather than have to trace OS/2 
memory management API func- 
tion calls all over your code, you 
have a central point to watch. 

This aliasing of DLL functions 
is not restricted to system service 
DLLs, but it can be used for any 
DLL. By using this simple tech- 
nique, you can lower the working 
set size of your application while 
making debugging easier. Some- 
times the things that give you ben- 
efits like this are the simplest and 
most often overlooked. 


David Reich has been with the IBM 0S/2 
development team since 1987. He has 
worked on many parts of the system, sup- 
ported customers and application develop- 
ers, and traveled the world giving semi- 
nars and teaching OS/2. He is currently 
working on the second edition of, 
Designing OS/2 Applications, published by 
John Wiley & Sons. He can be reached on 
CompuServe at 76711,632 or via Internet 
at speedracer@vnet.ibm.com. 
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The use of advanced technology, such as IBM's 0S/2 platform, has changed the methods and practices 
associated with testing applications. The introduction of robotic testing has answered many of the 
challenges associated with this new technology. By JOSEPH P. BUSA 


Advanced Technology 
Needs Advanced 
Testing 





Joseph P, Busa 


s part of a continuous quality- 

improvement effort in corporate 

systems at Empire Blue Cross 
and Blue Shield, the introduction of ad- 
vanced technology has caused a benefi- 
cial chain reaction in the project life 
cycle. Information systems is the nu- 
cleus that has to interface with all facets 
of our business. It is the hub of the 
wheel, with spokes that reach out into 
claims operations, membership services, 
and financial and other decision-making 
aspects of the corporation. 

Introduction of new programming 
technology, such as the OS/2 platform, 
has created challenges for traditional 
testing methods. We can no longer ex- 
pect to test these applications using 
methods of old. Whereas traditional 
mainframe systems may have a strictly 
defined path to follow to accomplish a 
task, graphical interface technology has 
exploded the possibilities and paths to 
take. A narrowly defined testing sce- 
nario may have been acceptable yester- 
day, but a wider scope is required today. 

The realization that a wider scope 
has to be tested and that the personal 
computer platform is being used makes 
it clear that a new way of thinking has 
to take place. Customers are becoming 
more aware that they are in the driver's 
seat. They are expecting quality prod- 





ucts so they can satisfy their customers’ 
requirements. 


THE FRONT LINE 

Empire is the largest health insurance 
business in the country. We handle in 
the neighborhood of 100,000 claims and 
inquiries per day. The complexity of 
processing, the variety of products of- 
fered, and the numerous business rela- 
tionships with health care professionals 
all come together in our data processing 
systems. With increasing competition in 
the health care market, our internal cus- 
tomers, claims examiners, and customer 
services representatives recognize and 
require many levels of independent test- 
ing of their products before they accep- 
tance test it themselves. 

The many features that OS/2 offers 
to the developer, such as drop-down 
menus, scroll bars, and profiling capabil- 
ity can make processing more efficient 
and easy to perform. These features cre- 
ate customer satisfaction. They give the 
application real value but cause sizable 
challenges to the testing community. 
Multitasking is a good example of a fea- 
ture that truly creates value in an applica- 
tion but is rather complex for testers. The 
testing staff on the front line requires an 
understanding of these functionalities to 
test the application effectively. 
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_ PLANNING AND TESTING METHODS 

| One of the most important aspects 
i of our testing is planning. Our com- 
pany is fortunate to have developed 
a project life cycle methodology, and 
it is used in the development of new 
systems, applications, and projects. 
This methodology calls for involve- 
ment of testing personnel in the re- 
quirements phase. 
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Test scenarios can be designed 
as requirements are stipulated. 
Testers get involved early in the 
development process, giving them 
more time and a better under- 
standing of what needs to be 
tested. Well-trained testing ana- 
lysts are critical to the success of 
testing. Organization of data, such 
as the use of a matrix format, is 
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Figure 1. Executive station connected to multiple agent stations. Independent tests can 


be run on each agent. 
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one way to document the arrange- 
ment of criteria for testing. Each 
scenario that is created is a box on 
the matrix. In our case, we inven- 
tory the scenario so it may be used 
again depending on what type of 
testing we are planning to per- 
form. This is especially useful for 
regression testing. 

The execution of test scenarios 
in a complex environment is an- 
other critical aspect of testing that 
new, advanced technology has im- 
proved for us. Performing a field- 
by-field comparison of data, espe- 
cially attempting to cover all the 
possible paths that can be taken in 
an OS/2 environment, has taken 
us weeks in the past. The intro- 
duction of robotic testing tools has 
answered the challenge of these 
new technological platforms and 
significantly reduced the effort. A 
test that took a week before is 
now accomplished in a day. 
Automated Testing can be used in 
multiple ways, and new auto- 
mated testing strategies are being 
formulated by our test team on a 
regular basis. Vendors of this tech- 
nology have been particularly 
helpful in assisting with the de- 
velopment of new approaches and 
in networking us with other cus- 
tomers for idea sharing. 


OUR AUTOMATED TESTING FACILITY 

After evaluating some of the in- 
dustry’s automated testing tools, 
such as Sterling’s TestPro and 
Sequel Corp.’s ProTerm, we de- 
cided on Softbridge’s ATF product 
since it happened to fit the needs 
of our operation. ATF is one of the 
few testing products we have 
found that can operate on multiple 
platforms, including OS/2. This fa- 
cility has two major components: 
the executive and the agent (as il- 
lustrated in Figure 1). The execu- 
tive directs the activity of test 
workstations or agents and con- 
tains the editing facility to develop 
the instructional script. The execu- 


tive acts as a command center from 
which testers can control and 
watch the execution of complex 
test scenarios. ATF has a sense of 
time and can also operate unat- 
tended. We plan on connecting as 
many as 50 workstation agents to 
one executive, giving us many op- 
tions for testing. Throughput of 
data can be greatly enhanced by 
giving 20 stations 50 test scenarios 
each instead of using 1,000 scenar- 
ios at one station. A configuration 
of 50 agents can also be used to 
simulate production environments 
and to execute stress testing. 

The core of the facility is the 
Distributed Test Language (DTL). 
This coding language allows users 
to perform any functionality they 
could normally do if they were sit- 
ting at the workstation them- 
selves—and more. Mouse move- 








Point and click 


ments, button selection, and key- 
strokes are all supported. 

Users also have the ability to 
reboot the agent from the execu- 
tive station. This can be convenient 
when certain error conditions are 
encountered during the execution 
of a script. Users can also use it to 
log the execution of script com- 
mands, allowing them to see re- 
sults of the tests. One of the big 
problems with testing graphical 
user interface types of applications 
is reexecuting a test on a newer re- 
lease of OS/2 or an application 
where the graphical windows have 
been changed ever so slightly—po- 
sitional changes, for example. ATF 
has the ability to recognize graphi- 
cal differences and, in most cases, 
permits scripts to run without 
change. Other features such as 
bitmap snaps and text snaps of the 


| click your way to fast development 
| of GUI client-server applications. 


jo it with Guidelines, a second-generation object- 
_f oriented graphical workbench. Guidelines lets you graphical, platform-independent applications. Its scal- 


screen, window, or area can be in- 
valuable in the development and 
debugging process. 


PRACTICAL APPLICATION 
At Empire, one of the first testing 
procedures we applied this tech- 
nology to was performance testing. 
ATF can accurately capture, to the 
second, response times of an appli- 
cation. With over 200 separate tim- 
ings, this is impractical and nearly 
impossible for human testers. 
We've established a procedure 
where each time a new release of 
software comes to the testing area, 
it is performance tested. That data 
is put to a database and then graph- 
ically displayed to show the ongo- 
ing history. For example, in our 
document imaging environment, 
performance tests on image re- 
trieval times were developed and 


Guidelines saves time and simplifies the creation of 


| create graphical client/server applications for OS/2 able architecture lets you create anything from stand- 


| and Windows clients. A built-in 
| prompter lets you simply point 


the desktop using more than 30 
presentation manager controls. 

Guidelines utilizes JBA's high- 
level object-oriented language 
(JOT) to describe applications. 
After the application is 
designed, JOT automatically 
converts to C++ code, so you 
don't have to learn its complex 





syntax and rules. But if you already 
want to use it directly, you can. The conversion takes 
| place regardless of the platform intended. 
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used to report on the performance 
of new software releases. As a reg- 
ular process, retrieval performance 
continues to be monitored and has 
been improved with each major 
software release. Overall perfor- 
mance has increased by over 30% 
since the first measurement. 

We have also developed a re- 
gression exercise that uses an inter- 
nal data table feature. The internal 
data table is a spreadsheet-like fa- 
cility from which scripts and tapes 
can read data and then apply that 
data to the application. In our re- 
gression tests, we have developed 
claims data that are run through 
and automatically compared with 
baselined results. Any expected re- 
sult that is not matched with that 
of the baseline is documented in 
the log in a tester-customized re- 
port format. The results may then 
be easily examined by the test ana- 
lysts. This has made our regression 
testing much more efficient. 
Attrition and downsizing has de- 
creased testing staff by 15%, yet 
the testing being accomplished has 
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Figure 2. Empire's OS/2 platform with 
application PC/System 90 at the 
“Welcome Screen.“ 


not diminished, and in some cases 
it has increased. 

Another method we have de- 
veloped is a “mapping” test. In our 
case, the OS/2 application, PC 
System 90, interfaces with a large 
IBM mainframe package system, 
as shown in Figure 2. PC System 
90 acts as a friendly front end to 
the mainframe claims system and 
converts certain data fields. It then 
uploads the data interactively to 
the mainframe. We need to know 
from version to version if this 
process is occurring without de- 
fects. We have written a script to 
capture and compare the input to 
the PC System 90 front end with 
the resultant input on the main- 
frame. Once again, a baseline ap- 
proach is used, and the data is au- 
tomatically compared by ATF. Any 
errors are flagged and examined 
by the testing staff. 

To fully leverage our quality- 
improvement initiative, we see op- 
portunity in introducing this test- 
ing method in the software 
development phase to use in a unit 
test mode. This will uncover and 
prevent defects from continuing 
further into the project life cycle 
and will advance the concept of 
doing it right the first time. 
Coming from a software develop- 
ment background, I’ve experi- 
enced the lack of detail knowledge 
with the data that will pass 
through the system. Using a ro- 
botic tool with a testbed of data de- 
veloped by team members that do 
have this detail knowledge will be 
a great advantage in unit testing. 


VALUE OF IMPROVED QUALITY 

AND PRODUCTIVITY 

The adoption of methods such as 
automated testing and full life 
cycle involvement has brought a 
sense of realism to our improve- 
ment initiative. Any organization 
that can do more with less without 
compromising quality will soon 
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come to the realization that work- 
ing smarter not harder is what will 
benefit the bottom line and the 
front line. It is a win/win situation 
for all involved. In our case, re- 
gression testing, which in the past 
involved one resource for three 
days, now takes that same resource 
less than one day to perform with 
even more accuracy. The staff's 
morale and job satisfaction has in- 
creased. The improved process 
leads to lower costs and higher 
productivity. The resultant evi- 
dence is shown when quality soft- 
ware is put into production on a 
timely basis. This leads to cus- 
tomer satisfaction, and that is our 
ultimate goal. 


CONCLUSION 

As new technology is introduced 
to the business world, the organi- 
zations that take the risks and are 
determined to improve the current 
methods of operation will be the 
successful ones. Process improve- 
ment and reengineering can lead 
to big payoffs in quality and pro- 
ductivity. We need to take a look at 
our traditional processes, break 
them down into their components, 
and then apply visionary thinking 
to improve them. The develop- 
ment and use of products such as 
OS/2 and ATF were unthinkable 
50 years ago. For all of us to fully 
participate in the improvement of 
our work, we need to look toward 
the future and continue to apply 
quality concepts. 


Joseph P. Busa, COA, is the quality 
assurance manager for Empire Blue Cross 
and Blue Shield in New York, the largest 
Blue Cross/Blue Shield in the country, He 
is responsible for all data processing qual- 
(ty assurance at Empire. He received his 
CQA (Certified Quality Analyst} from the 
Quality Assurance Institute in Orlando, 
Fla., in 1990. He has a B.S. in business 
administration from New York State 
University at Oswego, New York. 


This article demonstrates using OS/2 as the development base to build products that support multiple 
platforms. By BRUCE LANDECK 


Multiple Platform 
Development 


ecause of the proliferation of PC 
B operating environments, com- 

mercial products need to support 
multiple platforms to reach the widest 
possible audience. This article demon- 
strates using OS/2 as the development 
base to build a real product that runs 
under four different environments. The 
design and coding techniques and tools 
necessary to maximize code sharing be- 
tween products and minimize mainte- 
nance costs are explained with examples. 


OVERVIEW 
When building a PC commercial appli- 
cation, one of the first questions is, What 
is the target platform? In the past, the 
answer was obvious: PC/MS DOS. 
Today, while DOS is still a candidate, 
developers must also consider OS/2, 
Windows, and AIX/UNIX. DOS 
presently has the largest user base, but 
people are moving away from it. 
Windows has become very popular with 
a large user community, but it is being 
challenged by OS/2. And although 
OS/2 usage is growing rapidly, it will 
have to contend with Windows 95 
(Chicago). AIX/UNIX will never go 
away. 

One solution is to build for all of 
them or at least more than one. This ap- 
proach is practical only if you are able to 


write the application once and at build 
time determine the target platform. 
Otherwise, you end up writing multiple 
applications and, more importantly, 
maintaining multiple applications. 

Late last year, Spitfire Software was 
faced with this dilemma. We needed to 
upgrade a disk utility we market that 
targeted DOS and supported only a 
command line interface. It needed an in- 
teractive interface, additional function, 
and a broader audience. From an inter- 
face standpoint, both OS/2 Presentation 
Manager and Windows were attractive. 
The command line version was still a re- 
quirement for use in batch files and 
REXX programs. AIX/UNIX would 
have to wait because of skills. Therefore, 
the four target environments we chose 
were: 

1, OS/2 Presentation Manager 

2.OS/2 command line (non-Presen- 
tation Manager) 

3. Windows 

4. DOS command line. 


TOOL SELECTION 

Next, we selected the development envi- 
ronment and tools. OS/2 was the logical 
choice for the development environ- 
ment, since it also supports the DOS and 
Windows environments and is a solid 
operating system. C++ was chosen as 
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the development language for 
portability and productivity rea- 
sons. The object-oriented nature, 
tight type checking, and functional 
richness of available libraries has 
made C++ a strong application de- 
velopment language. 

What we did not want to do 
was code the interactive interface 
for OS/2 Presentation Manager 
and Windows at the C++ level due 
to productivity concerns, A num- 
ber of graphical user interface tools 
on the market allow design of the 
interface at an object level and gen- 
erate the code. We considered two: 
Gpf Professional Developer's 
Toolkit and JBA International’s 
Guidelines. They both generate 
C++ code and interface to external 
C++ modules. We selected 
Guidelines for a number of rea- 
sons, none of which reflect nega- 
tively on Gpf. Guidelines provides 
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Figure 1. Date stamp copy—OS/2. 
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basic facilities that significantly in- 

crease productivity: 

1. It is a fully integrated develop- 
ment environment with work- 
bench-supporting design, 
implementation, test, and docu- 
mentation activities. 

2. It supports a full set of controls, 
including CUA 91 in both OS/2 
and Windows environments 
(using IBM CUA Common User 
Access Controls Library/2 for 
Windows applications). 

3. It supports Borland C++ compil- 
ers for both OS/2 and 
DOS/Windows and WatCom 
C++ and IBM's C Set++ for 
OS/2. 

4.Ilt supports multiple execution 
threads in both environments. 

5. It supports complete integration 
of external C++ modules, with 
the main module allowing as 
much application function 


placed in the external modules 
as desired. For writing the main 
module event processing func- 
tions, Guidelines provides a pro- 
prietary language, JOT, which is 
similar to Basic in appearances 
(modified to force structured 
programming) with C++ data 
typing added. It allows the addi- 
tion of in-line C++ statements. 
JOT is a full-function language 
in which small- to moderate-size 
complete applications can be 
written. 

We chose Borland’s C++ com- 
piler. Although there was no other 
choice considering we needed one 
that Guidelines supported for both 
OS/2 and DOS/Windows, it was a 
good selection. 


IMPLEMENTATION 
The basic design for the project 
placed the user interface manage- 
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ment functions and high-level ap- 
plication logic in the main module 
and all of the actual application 
function in separately compiled 
modules. One source code set was 
written for the application function 
modules, and a main module was 
generated using Guidelines for 
both OS/2 Presentation Manager 
and Windows environments. A 
second main module was written 
in C++ for the OS/2 and DOS 
command line versions. 
Developing the interactive 
user interface module with 
Guidelines was straightforward, 
and no special consideration was 
given to OS/2 vs. Windows ini- 
tially (Figures 1 and 2 show how 
the interface looked in both envi- 
ronments). We designed and tested 
the interface under OS/2. When it 
was complete, we tested it under 
Windows. At this point, we en- 
countered an irritant. While the 


Figure 2. Date stamp copy—Windows. 


Windows version had all of the 
components and the code ran cor- 
rectly, the interface did not look 
right because proportions and col- 
ors were different. We had to go 
back and fine-tune the interface for 

Windows. This was difficult be- 

cause in the design step you see 

how it looks under OS/2, not 

Windows. To see it under Win- 

dows, you have to build and exe- 

cute the Windows version. 

Implementing the C++ mod- 
ules was more complex. We ran 
into the following problems: 

1. The operating system header 
files (OS2.H, WINDOWS.H, and 
none for DOS) are quite different 
in specifying operating system 
data types. 

2. The OS/2 and DOS API's are 
very different. Although the 
Borland function library hides 
many of the differences, it does 
not hide them all. For example, 


JANUARY/FEBRUARY 


1995 


OS/2 provides an API call to 
copy a file while DOS does not. 
Also, OS/2 has both High 
Performance File System (HPFS) 
and file allocation table (FAT) 
file systems, while DOS sup- 
ports only FAT file systems. 

3. Guidelines provides its own 
string class, which is function- 
ally richer than Borland’s and 
has to be used in the OS/2 
Presentation Manager and 
Windows versions. It could be 
used in the OS/2 command line 
version but requires a 386 or 
higher processor. The DOS com- 
mand line version needed to 
support all x86 processors, so we 
had to use the Borland string 
class for that version. 

4.OS/2 has a flat address space, 
while DOS/ Windows is seg- 
mented and requires “memory 
model” considerations. 

5. Borland’s OS/2 compiler trans- 











lates the int data type to a long 
integer type (4 bytes), while the 
DOS/ Windows compiler con- 
verts it to a short integer type (2 
bytes). This causes a problem 
using Borland’s libraries’ data 
structures within JOT (which 
supports only short or long inte- 
ger types and does not recognize 
the int type). For example, the 
Borland date type structure: 


struct date { 
int da_year; 
char da_day; 
char da_mon; 


}; 


will result in da_year being long 

when compiled for OS/2 and short 

when compiled for DOS/ 

Windows. 

We solved each of the problems. 
The basic solution to the first four 
problems is to use the C++ condi- 
tional compile directives and macro 
facilities. To resolve which header 
files and macro definitions are used 
to establish the environment, every 
C++ module had at its beginning 
the statements in Figure 3. 

In Figure 3, __0$2__ is defined if 
you are compiling under Borland 
C++ for OS/2, and _Windows is de- 
fined if compiling for Windows. 
Neither is defined when compiling 
for DOS. 

In examining Figure 3, note the 
following: 

1. In the OS/2 section, "guirun.h" is 
included for access to the 
Guidelines string class. When 
working with a third-party class 
library, it is the header file that 
supplies the information neces- 
sary to use the methods and 
overloaded operators. The 
header file "os2.h" was included 
for two reasons: “guirun.h" 
requires it, and the module 
makes direct calls to the OS/2 
API. The three #define statements 
set compile time directives in 
"os2.h" and "guirun.h". 


2.In the Windows section, 
"guiwun.h" is the equivalent of 
"guirun.h". The header file "win- 
dows.h" is included because "gui- 
wun.h" requires it. 

3. In the DOS section, "strng.h" is 
required to use Borland’s string 
class. The two #define statements 
define macros that in the other 
sections were defined by the 
Guidelines and operating sys- 
tem headers and are used in the 
code when referencing variables 
shared by the main module and 
the application function mod- 
ules. Since we do not have the 
other headers in the DOS sec- 
tion, we needed to define them 
here. 

Originally, we had planned to 
use the Guidelines string class in 
all four versions, since it had to be 
used in the OS/2 Presentation 
Manager and Windows versions 
and was functionally richer than 
Borland’s string class. Therefore 
we made extensive use of that 
class’s methods. For example: 


GuiStrLen(a) ; 


returned the length of a string. 
This method was used in allocat- 
ing space for a char array to 
process the string "a" in a standard 
C manner. Later, when we discov- 
ered we could not use the 
Guidelines string class for the DOS 
version because of processor re- 
quirements, we were faced with a 
dilemma. Either we used condi- 
tional compile directives through- 
out the code (selecting either 
Borland’s or Guidelines’ methods) 
or we had to find a “least common 
denominator” that would work for 
both. The solution was easy. In the 
case of retrieving the string length 
for all versions, we changed the 
statement to: 


strlen((const char *) a); 


Both the Borland and Guidelines 
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string class provided for casting a 
string as a constant char array. 

To set various limits that de- 
pend on a flat vs. segmented ad- 
dress space or the file system being 
used, the macros in Figure 4 were 
defined. Borland does include a set 
of predefined macros for limits in 
"limits.h" that could have been 
used for the path and file name 
size values. The list was incom- 
plete from our standpoint, so we 
decided to create a list tailored to 
our needs. 

Conditional compile directives 
were used in the code itself for 
special cases, as illustrated in 
Figure 5. The Borland library han- 
dles many of the differences in 
code for the environments, but 
when directly calling operating 
system API's, you must handle 
the differences. For example, the 
application module that copies a 
file uses the API function under 
OS/2 but needs to do the physical 
copying itself under DOS and 
Windows. 

In Figure 5, the first part de- 
fines the common variables used in 
both environments and is followed 
by the variables used in only one 
environment. The code section 
starts with the code common to 
both, continues with code specific 
to one or the other environment, 
and ends with the common exit 
code. Also note that the macros in 
Figure 4 define the size of the 
buffers used in Figure 5. 

After examining Figure 5, it 
can be argued that what we have 
is in fact two separate programs 
built as one but as hard to main- 
tain as two. I would agree if this 
was the rule, but it is the only 
place in the application where the 
code itself needed to be different 
depending on the environment. In 
all other places, Borland’s com- 
piler handled the differences 
through its libraries. 

How the C++ int type is han- 
dled is a different problem because 


ects the JOT code, which does 
not support compile directives and 
macros. What JOT does is allow us 


passed directly through to the 
compiler. For example, if we have 
a variable that is shared with the 
lication C++ modules and de- 

as an int, we can process it as 
shown in Figure 6 (JOT uses a 
1icolon to denote the start of a 


comment). The one drawback of 
this approach is that the variable 
can be referenced by only in-line 
C++ code. 

Although the code fragment in 
Figure 6 is nonsense, it illustrates 
adding C++ code to JOT modules. 
Guidelines does let us create func- 
tions that are entirely C++. The 
problem is that it does not syntax 
check in-line C++ code at genera- 


Figure 3. External C++ module environment statements. 


Figure 4. External C++ module system parameters. 
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tion time. It is not until you com- 
pile the code that you discover er- 
rors. With JOT statements, 
Guidelines provides very rigorous 
checking, and if the code generates 
C++, you know it will compile. 
The last problem concerns 
memory models and processors. 
The solution here is quite straight- 
forward and handled by the make- 
files. One large makefile could not 
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Figure 5. Example external C++ function (continued on page 37). 
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Figure 5. Example external C++ function (continued from page 36). 


be used since the OS/2 build 
needed to take place under OS/2 
while the DOS/Windows build re- 
quired DOS. The Guidelines mod- 
ule required only instructions 
telling it which environment to 
build. For the external C++ code, 
three projects were set up under 
the Borland IDE: OS/2 (one project 
handled both Presentation Man- 
ager and command line), Win- 
dows, and DOS. They all use the 
same source code but have differ- 
ent compile time options and place 
their intermediate and final output 
in different subdirectories. The one 
small irritant is that a complete 
build requires the execution of the 
makefiles for the three Borland 
projects followed by the two builds 
of the Guidelines graphical user in- 
terface. It would be nice if 
Guidelines allowed the inclusion 
of the Borland makefiles in the one 
it generates. 


DOCUMENTATION: 

The on-line documentation and 
context-sensitive help was easy to 
implement under Guidelines, 


which has a complete help text 
generation facility built into it. 
During development of the OS/2 
Guidelines module, we added the 
help text as we went, creating 
hyper text links and organizing it 
in document form. This way we 
had both an online document the 
user could read and print plus con- 
text-sensitive help panels. 

At generation time, Guidelines 
generated the complete .IPF file 
for OS/2. For the Windows ver- 
sion, Guidelines generated the 
.RTF file converting our IPF tags 
to RTF tags. We encountered one 
problem here. Guidelines was 
able to translate many IPF tags 
but not all. We therefore had to 
edit the Windows help text, re- 
placing selected IPF tags with RTF 
tags. During the compile/link 
phase, the IPF/RTF files were au- 
tomatically compiled into the 
-HLP file and linked to the exe- 
cutable. A great side effect was 
that we were able to take the .IPF 
file generated by Guidelines and 
easily create the printed docu- 
ment shipped with the product. 
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SUMMARY 

As shown, the tools now exist to 
easily develop products for multi- 
ple platforms. Key to doing this is 
a thorough understanding of each 
platform and proper planning and 
design during the initial stage of 
the project. A strong multiple plat- 
form compiler is required, and a 
multiple platform graphical user 
interface design tool significantly 
increases productivity. 


Bruce W. Landeck js president of 
Spitfire Software (325 Breakwater Ridge; 
Atlanta, Ga. 30328; (404) 257-0187), which 
develops financial and utility software for 
multiple PC platforms. Bruce founded 
Spitfire Software in July 1993 after 30 
years of experience with IBM in software 
development. While at IBM, he held a full 
range of technical and managerial posi- 
tions, including lead programmer, archi- 
tect, product planner, development man- 
ager, product manager, and business area 
manager. He has a B.S. degree in 
Engineering Science from Purdue 
University and an M.S. degree in 
Aerospace Engineering from the University 
of Arizona. 
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Figure 6. Using C++ in JOT. 
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Memory leaks adversely affect your programs’ performance and can even cause your machine to 
stop processing. Here are five ways to avoid and plug memory leaks. By STEVE HARGIS and 


MIKE SKELTON 


Plug Those 
Memory Leaks! 


A 


ll computer programs use mem- 
ory, some for the program code, 
some for the data. Some pro- 
grams call libraries that then use more 
memory. Data can be held in numerous 
ways, such as structures, heaps, and 
stacks. The operating system itself will 
use memory on behalf of a program. For 
example, even the mouse pointer shape 
is held in memory for the program 
using it. Since program memory can be 
held by many owners in many ways, de- 
termining all the memory that is directly 
used by a program or indirectly used on 
its behalf is an involved task. In this arti- 
cle, we define different kinds of memory 
usage problems, offer some design 
guidelines to follow during program de- 
velopment, and show an approach to 
debugging memory leaks. 

Since a program uses memory in 
many ways, in many places, and with 
many owners, it would not be surpris- 
ing if some programs lost track of a little 
bit of memory every now and then. So 
what? Well, the consequences depend 
on how much and how fast the program 
loses track of its memory. 

Following are three examples of 
programs and the consequences of their 
memory use: 

1. A small utility program runs for a few 
seconds, doesn’t keep track of any of 





its memory, and relies on the operat- 
ing system to free its memory when it 
ends (and hopes no one notices). 

2. A business application that runs a few 
hours needs to seriously track its 
memory usage to prevent the user 
from perceiving any affect of lost 
memory. However, if the lost memory 
is large enough, the user will notice 
the application (and the system in 
which it runs) is becoming slower or 
encountering errors for mysterious 
reasons. The user may need to end the 
program and restart it to make the 
business application run well again. 

3. A mission-critical application that is 
expected to run 24 hours a day, seven 
days a week cannot afford to lose 
track of any memory at all because 
the entire system will become slow, 
unresponsive, and incapable of per- 
forming at required levels. 

All three examples need to manage 
their memory flawlessly. Plugging mem- 
ory leaks is an integral part of improv- 
ing reliability and performance. 


MEMORY LEAKS 

A memory leak is memory a program 
allocates (or that is allocated on a pro- 
gram’s behalf) that is not freed after the 
program is finished with it. If the same 
action is executed again, the program 
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Point. Click. And Presto! 


To create an application you draw user interface objects, customize their 
properties using standard OS/2 notebooks, and define their event code using 
powerful drag-and-drop programming. To add database access just draw a 
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allocates more memory instead of 
using memory previously allocated. 
With repeated executions, the pro- 
gram accumulates more and more 
memory. Negative affects of mem- 
ory leaks include the accumulation 
of memory by the leaking program 
causing other processes’ code or 
data to be swapped or paged out. 
Soon, the system's resources are 
consumed while the operating sys- 
tem swaps memory in and out in- 
stead of executing application code. 
This robs every process in the sys- 
tem of performance. 


MEMORY OVERWRITE/ 

MEMORY WALKER 

A memory overwrite occurs when 
a program allocates less memory 
than it actually writes. The effect is 
to overwrite and possibly wipe out 
data that happens to be located im- 
mediately after it in memory. 
Whether or not a memory over- 
write occurs depends on how 
many additional bytes are stored 
beyond the amount allocated. The 
observable symptom is intermit- 
tent data corruption, which is de- 
pendent upon the length of data 
stored in memory (not an intuitive 
item to check). 


MEMORY NEUTRALITY 

This is the desired memory use 

quality of programs. A module, 

component, function, API, pro- 

gram, system, and so on is said to 

be memory neutral if it: 

* Deallocates all memory for 
which it is responsible 

¢ Does not attempt to deallocate 
more memory than that for 
which it is responsible, 

The basic definition is straight- 
forward: deallocate all and only 
the memory that you allocate. 
However, when specification stan- 
dards call for a different module to 
deallocate memory than the mod- 
ule that allocated the memory, the 
definition gets a little fuzzy. This is 
not a recommended specification, 
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Now that we know what 
memory leaks are and how they 
affect the performance of an appli- 
cation as well as each process exe- 
cuting on a system, five recom- 
mendations follow that allow 
developers to detect and fix leaks 
early in the product development 
process. 


DESIGN AND PROGRAMMING 
RECOMMENDATIONS 

1. Know the memory usage of each 
component within the product. 

It is difficult to diagnose mem- 
ory problems when no one knows 
how the product is supposed to 
use memory. The logical person to 
know the memory usage is the de- 
veloper, who possesses some basic 
memory debugging skills and 
tools. 

To check your knowledge of 
the memory usage of your applica- 
tion, select a test case that is typical 
for a user. Assume that you are 
going to execute the test case while 
your application is executing. How 
much memory do you think will 
be allocated during the test case? 
How much memory will be com- 
mitted? Do not forget to specify 
whether the memory will come 
from the heap or be part of shared 
memory, and so on. 

Check your answers with a 
memory analyzer, such as The- 
seus2 (part of the SPM/2 
product).' With Theseus2, from the 
initial window, select the process 
executing your application, then 
choose the Memory Utilization op- 
tion from the Process item on the 
menu. When compared with re- 
sults before the test and results 
during the test case, the Total 
system, Total Shared originated, 
and Total Private rows will allow 
you to check your answers. (It may 
be desirable to explore memory 
further with Theseus2 to see ex- 
actly what memory was allocated 
by whom, what the contents are of 
some memory, or why the size al- 
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located is not the same as what 
your application asked for.) 

2. Do not rely on the operating 
system to delete memory when the 
process dies. 

This is common practice with, 
it would seem, no ill effects. It is 
true that the operating system will 
deallocate resources when the 
process dies, but that works only 
for relatively short-lived processes. 
Major processes that stay up for 
days, weeks, or months should not 
be implemented that way. There 
are five main reasons 24/7 
processes and, arguably, even 
shorter-lived processes should not 
rely on the operating system to 
delete resources. 

First, resource consumption 
will grow over time, and the oper- 
ating system may not clean up 
memory structures in a timely man- 
ner. For example, if memory is allo- 
cated to store information until a 
process dies and the process does 
not die for three weeks, the infor- 
mation stored will consume a lot of 
memory. Consuming a lot of mem- 
ory will cause memory (Wherever it 
is used the least) to be swapped. It 
will not take long for the swapper 
file to be so large that it adversely 
affects the performance of every- 
thing that runs on the machine. 

The second reason is that the 
code may be ported or expected to 
run on a different operating sys- 
tem or platform with different 
clean-up characteristics. The new 
platform may not clean up re- 
sources as nicely as OS/2. Or per- 
haps the other platform does clean 
up nicely today, but it may not in 
the next release. 

Reason three relates to device 
drivers. Device drivers can, and 
many do, allocate locked and resi- 
dent memory on behalf of an ap- 
plication. Unless this memory is 
deallocated by the device driver, it 
will always be allocated. 

A fourth reason to not rely on 
the operating system to delete 


memory when a process dies is that 
program design changes may alter 
the operating system’s ability to 
clean up memory structures. Code 
may originally be written to run in 
a process of its own, but the process 
or thread model of products is sub- 
ject to change. Code may be consol- 
idated from several processes into a 
smaller number of longer-lived 
processes to avoid process creation 
and deletion overhead. Therefore, 
code that started out in a process of 
its own may be consolidated to run 
on threads of a process containing 
other threads. Resources such as 
memory, semaphores, and files are 
owned by the process, not by the 
thread. So when the code now ter- 
minates the thread, the process re- 
mains—along with all the resources 
accumulated by the thread but 
never freed. 

The last reason is that debug- 
ging is greatly complicated by not 
knowing whether memory is sup- 
posed to be unallocated by the op- 
erating system or if a memory leak 
exists. We advocate use of the C 
Set/2 and C/C++ debug memory 
functions.” When using them, we 
have noticed that many programs 
are not memory neutral at the in- 
struction immediately prior to re- 
turning control to the operating 
system. So if we are trying to fix a 
memory leak, we must first get 
through the “noise” of memory 
that is supposed to be cleaned up 
by the operating system (we say 
that memory was leaked purpose- 
fully) to memory that is being 
leaked accidentally. This is an ex- 
tremely time-consuming activity, 
especially if the developer does not 
know the memory usage of his or 
her component. 

Let us close this recommenda- 
tion by saying that sound coding 
practices include allocating ma- 
chine resources as needed, tracking 
those resources, and deallocating 
them at the earliest reasonable 
time. Relying on the operating sys- 


tem to clean up a process’s use of 
resources is dangerous in today’s 
cross-platform code environment. 

3. Avoid designs where one mod- 
ule allocates memory and another 
module deallocates it. 

The exception, of course, is 
when the design specification 
comes from a standards institute 


and you have no control over it. 

This sort of design can lead to the 

following problems: 

* Poor communication between 
memory allocation and dealloca- 
tion modules, or developers, will 
lead to memory leaks. 

e There is an increased possibility of 
several modules using different 
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linking conventions (for example, 
optlink and syslink). This causes 
applications to leak memory since 
memory allocated under one link- 
ing convention may not be recog- 
nized under another. 

Few people, if any, will really 
know who is allocating what for 
what or who can deallocate or 
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Communicating that to team 
members will be extremely diffi- 
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ent compilers used in the product. 
Using multiple C run-time li- 
braries to compile different mod- 
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ules will lead to memory leaks be- 
cause run-time libraries do not im- 
plicitly communicate with one an- 
other. A corollary to this suggestion 
is that different versions of the 
same compiler often have the same 
problem because the header files 
used to make the libraries are not 
the same between versions. It is ex- 
tremely difficult, if not impossible, 
to cleanly separate functions within 
modules or modules within appli- 
cations among different C run-time 
libraries. They inevitably will want 
to communicate, but compilers do 
not support communications across 
run-time libraries. 

5. Set the criteria for determining 
memory neutrality early in the devel- 
opment cycle. 

We recommend that memory 
neutrality be a test exit criteria be- 
ginning with the functional verifi- 
cation test. If an application has 
memory problems, finding and fix- 
ing them as soon as possible in as 
small an environment as possible is 
much easier than waiting for tests 
in a large, complex environment. 


DEBUGGING TECHNIQUES 

AND TOOLS 

OS/2 memory usage includes 
these three facts: when a program 
allocates memory, it acquires a 
memory object; memory is owned 
by the process that allocated it; and 
a program may have multiple 
threads of execution in a process. 
So a memory object allocated by 
any thread is owned by the process 
and may be shared between all of 
the threads in the process. 

When debugging, the first 
question to ask is, Which of the 
many processes running in the sys- 
tem have memory leaks? Once the 
leaking processes have been deter- 
mined, the next question is, Which 
memory objects in the processes 
have memory leaks? The last ques- 
tion to ask is, What piece of code is 
allocating the memory objects and 
what should be deallocating them? 


In the remainder of the article, 
we describe how to discover if 
your application is leaking mem- 
ory. If you do have a memory leak, 
our detection technique will 
quickly indicate which part of 
your application is responsible. 
Useful tools to complement our 
technique are also discussed. The 
first necessary tool is a memory 
analyzer, which opens access to the 
entire contents of memory. The 
second is part of the IBM C Set/2 
or IBM C/C++ compiler.* Other 
compilers or third-party add-on 
products offer similar capabilities. 
Detailed discussions and examples 
using these tools are available.* 

Depending on the type of leak, 
you can use either a memory ana- 
lyzer or compiler tools to diagnose 
the cause of the memory leak. Since 
leak detection begins with a mem- 
ory analyzer, we will cover them 
before we cover compiler or com- 
piler add-on tools that are helpful. 


MEMORY ANALYZERS 
Maneuvering through the laby- 
rinth of OS/2 memory structures is 
a chore that few developers try to 
complete. Fortunately, tools exist 
that will navigate through OS/2 
memory and report what is occur- 
ring. Memory analysis is made 
possible by tools that access sys- 
tem and kernel memory; report on 
process and memory object owner- 
ship; understand linear and physi- 
cal memory addressing; can access 
shared, swapped, and present 
memory; and detect memory leaks, 
among many other capabilities. 
Theseus2 is the most complete 
OS/2 memory analysis tool avail- 
able; its documentation and online 
help contain years of memory de- 
bugging experience and advice (in- 
cluding an “Explanation of the 
contents of this window” menu 
choice for every window). A tutor- 
ial for the memory leak detection 
functions of Theseus? is available.’ 
To confirm that a memory leak 


exists, use the system level mem- 
ory leak detection function in 
Theseus2. When a memory leak 
exists, Theseus2 will report that a 
process (or processes) is not deallo- 
cating all of the memory that was 
allocated. (Focus your attention on 
the processes that you can start 
after the leak detection function 


has started and the processes that 
complete before the leak detection 
function has completed. Thus you 
would usually ignore system and 
Presentation Manager processes.) 
By confirming the existence of 
a memory leak, we have also dis- 
covered which process is leaking 
(this is called system level leak de- 
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tection). With this knowledge, we 
would apply the memory analyzer 
to only the process that is leaking to 
discover which memory objects are 
leaking (this is called process level 
leak detection). In Theseus2, this 
would require use of the “Memory 
Object Leak Detection” function, 
which monitors a specific object in 
memory and reports the status of 
each page within the object (this is 
part of object level leak detection). 
As time progresses, changes in the 
status of a page are reported along 
with a detailed description of what 
changed at what memory address. 
This information is extremely help- 
ful because we can learn: 

¢ The size of the memory object 

¢ The contents of the memory 

object 
¢ The status of each page within 
the memory object. 





OS/2" is a great operating system - 
except when it comes to delivering a 
consistent desktop time after time. It's so 
easy to drag and drop system files and 
utilities into the shredder. Anyone can 
do it. Now that's an administrative 
nightmare. 


Unless you have the Desktop 
Observatory ™ from Pinnacle 
Technology. The Desktop Observatory 
silently takes control of your user 
desktops. 


Theseus2 allows leak detection 
in a manner that continually nar- 
rows the search. The results from 
system level leak detection indi- 
cate a process or processes; the 
process level indicates a memory 
object or several objects; and object 
level leak detection indicates a 
page or set of pages. Each level of 
leak detection points to a lower 
level of memory abstraction until 
memory pages are reached. 

Armed with this information, 
we can find the developer respon- 
sible for using that memory object 
and determine if the behavior we 
are seeing is expected. It can be 
helpful to ask questions such as, 
Do you recognize the data in this 
memory structure? What size 
should this memory structure be? 
Is the size of this memory structure 
static or dynamic? When was this 
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memory structure allocated and 
when is the earliest possible time 
that it can be deallocated? If the de- 
veloper can answer these questions, 
then either the design included a 
memory leak (that is, the developer 
never planned to deallocate the 
memory) or comparing the answers 
to the code will uncover a discrep- 
ancy between the design and the 
implementation. Either way, the 
memory leak will be obvious. 

If the developer cannot answer 
the questions, you may have to 
continue your debugging using the 
compiler tools discussed ahead. 
You may also want to refer that de- 
veloper to the first design and pro- 
gramming recommendation at the 
beginning of this article. 

A useful memory analyzer will 
allow you to analyze memory from 
several perspectives. Depending 
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on how much you know about the 
memory leak at hand, analyzing at 
the system, process, thread, exe- 
cutable, or memory object level can 
be helpful. Being able to monitor 
swapper file growth and page 
swapping is also helpful in deter- 
mining if a memory leak exists. We 
have used Theseus2 to detect and 
solve many memory leaks by first 
determining which process is leak- 
ing and then examining that pro- 
cess in finer granularity until the 
actual memory object being leaked 
is found. Once you know the mod- 
ule or memory object that is leak- 
ing, you can apply the compiler 
debug memory tools if necessary. 


COMPILER TOOLS 

The IBM C/C++ Tools compiler 
contains a battery of debug mem- 
ory management features. These 
features consist of debug versions 


of the calloc, free, _heapmin, malloc 
and realloc functions. The debug 
versions are, respectively, _debug_ 
calloc, _debug_free, _debug_heapmin, 
_debug_malloc, and _debug_realloc. 
There is also a _dump_allocated func- 
tion that outputs information 
about every memory object on the 
heap. (Version 2 of the compiler 
also supports debugging the new 
and delete operators.) 

The compiler can be told to 
use the debug versions of the 
memory management functions in- 
stead of the regular versions at 
compile time with a compiler 
switch. When you turn the switch 
on, each memory function call au- 
tomatically invokes its debug 
equivalent and another debug 
memory function called _heap_check. 
_heap_check performs a thorough 
check of the heap, its memory ob- 


jects, and all associated pointers. If 


anything is out of order, processing 
is aborted and a diagnostic mes- 
sage is output on stderr. At first it 
may be annoying that processing is 
aborted, but it is helpful to know 
that memory was overwritten or 
that a bad pointer was passed to a 
memory function. 

When a program aborts due to 
memory errors, it is common for 
the run time to indicate that the 
error was before or after module x 
line y. An error message like this 
indicates that an error was just de- 
tected; therefore, the actual error 
occurred between the line refer- 
enced in the message and the last 
memory function called (specifi- 
cally, the last _heap_check per- 
formed). Finding the memory 
function that executed just prior to 
the one flagged is usually easy, but 
it can be quite difficult in a multi- 
threaded environment. The hunt is 
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worthwhile, however, since there 
are many benefits to letting the 
compiler find memory errors. 

The compiler is the definitive 
source as to whether or not a mod- 
ule has memory leaks. A home- 
grown memory check scheme may 
suffer from the same blind spots as 
the code it was intended to check. 
We know of no better way to en- 
sure that the memory management 
functions are used in a memory 
neutral way than to use a compil- 
er’s debug memory management 
features. Some memory errors are 
detected only when the memory 
debug functions are turned on (for 
example, passing a bad pointer to 
free and some memory overwrites). 

Generally, compiler tools are 
not hard to use; although some 
code additions may be required for 
C++ code that redefine or overload 
the new and delete operators. We 
recommend locating the point in 
your code where you return con- 
trol to the operating system (your 
code should be memory neutral 
here). Just prior to this point, add a 
call to the _dump_allocated function 
that is conditional based on a flag 
the compiler turns on when the 
debug memory management calls 
are used. For example: 


#ifdef __DEBUG_ALLOC__ 
_dump_allocated(16) ; 
#endif 


It can also be useful to use 
_dump_allocated before and after a 
function, operation, or test case is 
executed to determine if the func- 
tion, operation, or test case is actu- 
ally memory neutral. 

After compiling with the 
debug memory options turned on, 
your application may behave dif- 
ferently. It will definitely execute 
more slowly—approximately dou- 
ble previous execution times. 
When the heap is in a good state, 
you should be able to run a test 
case and then shut down your ap- 


plication. Just before control is re- 
turned to the operating system, the 
_dump_allocated call will print infor- 
mation about heap storage that is 
still allocated. Ideally, it will say 
that your application has no stor- 
age allocated. If you do have stor- 
age allocated, then you have a 
memory leak! The report is sent to 
stderr and includes the line num- 
ber and name of the module that 
allocated the memory, the pointer 
that points to the memory, how 
much memory was allocated, and 
the first 16 bytes of that memory 
location (the parameter 16 can be 
changed to as much or as little as is 
helpful to you). 


SUMMARY Re LLYN 
Customers are demanding applica- 
tions that can maintain peak per- 
formance for weeks or months 
without needing to be mestarted. 
Even small memory leaks will 
cause an application to grind the 
entire system to a halt; so detecting 
and plugging memory leaks is an 
important part of performance. 
Compiler debug memory fea- 
tures and memory analyzers are 
indispensable tools in avoiding 
and plugging memory leaks. 
Memory analyzers allow memory 
leaks to be quickly detected; they 
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can also be used to narrow the 
hunt to specific modules or mem- 
ory objects. Compiler debug mem- 
ory tools can then be used to moni- 
tor the behavior of specific 
modules and to flag incorrect 
memory usage. 

Nothing beats having the right 
tools for the job! 
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he graphical toolbar is a popular 

concept used to improve the us- 

ability of graphical-user-inter- 
face-based applications. As applications 
suffer from expanding “featuritis,” search- 
ing for commonly used functions in a 
text-based menu bar can become quite 
tedious. A toolbar gives a user the abil- 
ity to bypass the text menu bar and have 
direct access to the most commonly 
used functions. Its graphical and in- 
tuitive visual appearance gives the appli- 
cation a sophisticated look and feel. Tool- 
bars have almost become the norm for 
even moderately complex applications. 

For the Presentation Manager devel- 
oper looking to provide this type of 
function, the task is daunting, since 
Presentation Manager contains no na- 
tive support for this kind of graphical 
control. The graphical requirements 
alone are a significant programming ef- 
fort. Add to that the code for user cus- 
tomization of the toolbar, and it adds up 
to a significant project in itself. All of 
this is overhead to the essential func- 
tions of the application. 

We present here a custom Pre- 
sentation Manager control that sports a 
number of different styles and arrange- 
ments of bitmaps to produce a variety of 
visual effects (as illustrated in Figure 1). 
By using this control, a Presentation 





Toolbars are becoming the norm for all types of applications. This article presents a custom Presentation 
Manager control that saves developers a large amount of the effort and code maintenance required 

to support a tool bar. By MARK McMILLAN, GENNARO CUOMO, JURG VON KANEL, and 
GUILLAUME LE STUM 


A User-Customizable 
Toolbar Control 


Manager developer is saved the large 
development effort and code mainte- 
nance required to support a toolbar. 
This, in turn, allows more development 
resource for basic application function- 
ality and a shortened development 
cycle. No expensive graphical user inter- 
face builder tools or class libraries are 
required—just an OS/2 2.x compiler, the 
standard OS/?2 toolkit, and the run-time 
code supplied in the package. The run- 
time code may be statically or dynami- 
cally linked. 

The control was originally con- 
ceived at the IBM Yorktown Research 
laboratory by Gennaro Cuomo and Jirg 
von Kanel for use in EPM (the OS/2 en- 
hanced system editor). Its value for gen- 
eral application development was recog- 
nized, and the design was generalized 
into a prepackaged custom Presentation 
Manager control, with subsequent de- 
velopment contributions from 
Guillaume Le Stum, John Ponzo, Alan 
Warren, and Alex Bertrand. Mark 
McMillan of IBM Research Triangle Park 
developed the sample code and frame 
control utility functions and initiated 
improvements in the architecture. An 
earlier version of this control appears on 
the OS/2 Developer Connection CD 
Volume 4. The current version contains 
many improvements and new samples. 
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Aside from the good graphical pre- 
sentation, the most significant features 
of this control are the easy user cus- 
tomization methods it provides (thus 
the name, UCMenus). Customizing a 
UCMenu is made easy for the user by 
extensive use of direct manipulation 
techniques. For example, to delete an 
item from the toolbar, the user can drag 
the item to the system shredder. Re- 
ordering the items is as easy as dragging 
the item to a new position and dropping 
it. Table 1 shows all the direct manipula- 
tion functions provided by UCMenus. 

Clicking the context mouse button 
on a UCMenus toolbar pops up a con- 
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text menu that allows the toolbar styles 
to be changed and items to be added 
and deleted (as shown in Figure 2). The 
control has built-in dialogues that allow 
the user to change the bitmaps, text, and 
application function associated with any 
menu item. Figure 3 shows the notebook 
used to associate the menu item with an 
application function. 

All customization is encapsulated in 
the UCMenu control itself. The control 
and the application cooperate via mes- 
sages to provide application-specific in- 
formation during customization. Using 
the built-in customization methods the 
user can: 
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Figure 1. 7 standard frame window with four UCMenu toolbars. 
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¢ Modify styles related to visual 
effects 


e Add and delete items and sub- 


menu items 

¢ Replace bitmaps with .BMP files 
or application-supplied bitmaps 

e Edit the text under the bitmap 

¢ Associate application functions 
with menu items (the applica- 
tion supplying the list of valid 
functions) 

¢ Move/copy menu items within 
a menu or between menus 

¢ Restore the entire menu to an 


Customization 


application-defined default 
state. 

The application can restrict 
what customization functions are 
allowed, which we will discuss 
later in this article. 


UCMENU STYLES 

Like many Presentation Manager 
controls, the visual appearance of a 
UCMenu can be modified through 
the use of “style” flags. Figure 1 
shows an application with toolbars 
of several different styles. 


a a — 





Figure 3. The built-in UCMenus customization notebook. 
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UCMenu toolbars can have a verti- 
cal, horizontal, or matrix layout. 
The bitmap items can be drawn 
with or without three-dimensional 
frames, text underneath, and fixed 
or automatic sizing. Individual 
items can be highlighted with a 
check-mark attribute and are 
drawn with thick dark borders. 
Background colors of the menu 
items and empty toolbar spaces 
can also be controlled. When re- 
quired by window size, scrollbar 
controls will automatically appear 
at each end of the toolbar. 


UCMENU PROGRAMMING CONCEPTS 
Several key concepts need to be 
understood to make effective use 
of UCMenu controls in an applica- 
tion program. As its name implies, 
the basic paradigm of a UCMenu 
control is that of a normal 
Presentation Manager text menu; 
the control contains selectable 
items, submenus, separators, item 
attributes, and so on. (The current 
implementation is limited to a sin- 
gle level of submenus.) As we will 
see, the developer’s view of this 
control is also similar to that of a 
Presentation Manager menu con- 
trol. This similarity is by design 
and allows anyone familiar with 
Presentation Manager menus to 
grasp the terminology, concepts, 
and messages involved with 
UCMenu controls. It is important 
to recognize that there are some 
key differences, many of which we 
will cover in this article. 

The UCMenu control uses 
many of the same menu-related 
messages and data structures as its 
Presentation Manager menu coun- 
terpart. (In fact, a real Presentation 
Manager menu is used “under the 
covers” of the UCMenu control, 
but that is hidden from the appli- 
cation.) For example, a MM_QUERYITEM 
message can be sent to the 
UCMenu window to obtain a MENU- 
ITEM structure that describes a par- 
ticular item in the menu. The ap- 


plication will receive all the stan- 
dard Presentation Manager menu 
notification messages except 
WM_DRAWITEM and WM_MEASUREITEM, 
which are used internally by the 
UCMenu, and WM_COMMAND, which is 
replaced with a WM_CONTROL message. 
Because of its added visual 
and interactive complexity, the 
standard Presentation Manager 
menu structures and messages are 
not sufficient to implement a cus- 
tomizable graphical menu bar. 
Thus, UCMenus adds another 
layer of messages and data struc- 
tures on top of the Presentation 
Manager menu architecture. It is 
important to understand the new 
concepts that UCMenus brings to 
the existing menu architecture and 
how the Presentation Manager 
menu architecture has been ex- 
tended to accommodate them. 


UCMenu Action Strings. One of the 
most important new concepts that 
UCMenus brings to a menu is that 
of actions. An action is a textual de- 
scription of the function assigned 
to a particular menu item. It is an 
arbitrary string defined by the ap- 
plication and seen by the user 
when customizing a UCMenu. It is 
usually a short two- or three-word 
phrase that defines the application- 
specific function the menu item is 
to perform when selected. For ex- 
ample, a text editor might define 
action strings like: 


"Copy to Clipboard" 
"Paste from Clipboard" 
"Left Justify" 

"Select Fonts" 


When creating a new UCMenu 
item or modifying an existing item, 
a user will select from a list of ac- 
tions supplied by the application. 
Applications that use Pre- 
sentation Manager menus often as- 
sociate specific application func- 
tions with specific item IDs. Figure 
4 shows the typical processing of a 


WM_COMMAND message from a Pre- 
sentation Manager menu control. 
The application function selected 
in the switch statement is based on 
the item ID supplied by the menu 
control in mp1. 

For a UCMenu control, the 
item [Ds are arbitrary and can 
change during execution of the 
program. An application cannot 
know ahead of time what the item 
IDs are going to be for any particu- 
lar menu item. To understand why, 
consider what happens when a 
user adds a new menu item to an 
existing UCMenu toolbar. The 
UCMenu control supplies all the 
user interface necessary for the 
user to choose a bitmap, text, and 
an application-specific action for 
the new item. When the new item 
is added to the menu, the UCMenu 
control will choose an arbitrary 
item ID that is unique throughout 
the menu and all submenus. 
Likewise, items can be moved and 
copied between UCMenu toolbars. 
The resulting (new) menu items 
are assigned arbitrary [Ds that do 
not conflict with any existing 
items. 

The implication for the appli- 
cation is that it cannot depend on 
using item IDs to determine what 


function was selected on a 
UCMenu toolbar. Instead, the ap- 
plication must use the action asso- 
ciated with the menu item to deter- 
mine what function has been 
selected. A UCMenu control will 
send a WMH_CONTROL message with a 
notification code of UCN_ITEMSELECTED 
when an item is selected. The ap- 
plication will not receive a WM_COM- 
MAND message from a UCMenu 
control. 

The application must associate 
the action string of the selected 
menu item with an application 
function. The toolkit sample pro- 
gram (SAMP1.C) uses a table that 
maps action strings to fixed ID val- 
ues. The action of the selected item 
is looked up in the table and then a 
simple switch can be used to select 
the correct application function in 
a manner similar to the original 
WM_COMMAND processing in Figure 4. 
The ID values chosen for the table 
purposefully match the fixed item 
IDs used in the applications stan- 
dard Presentation Manager menu 
bar (the application has both 
UCMenu toolbars and a standard 
Presentation Manager menu bar). 
Thus, the same switch can be used 
to process WM_COMMAND messages from 
the Presentation Manager menu 





Figure 4. Processing a typical Presentation Manager menu selection. 
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ot Fikwabata and WM_CONTROL messages from the 


UCMenus. This reduces code size 


USHORT ItemID; poh ans es 
hee i: and keeps application-specific 
functions from being duplicated. 
#define MAX_ACTIONS 4 The combined method for process- 
struct { /* Table to map action strings to fixed IDs +/ ing both Presentation Manager 

USHORT CmdID;  /* Unique ID for each menu item +/ menu and UCMenu selections is 

PSZ_ = Action; /#* Unique ‘action’ string */ shown in Figure 5. 

} ActionTable[MAX_ACTIONS] = { A list of all UCMenu-related 
{ID_COPY, "Copy to Clipboard" =}, messages is shown in Figure 6. The 
{ID_PASTE, "Paste from Clipboard" }, messages are grouped by messages 
{ID_LJUSTIFY, "Left Justify" }, the UCMenu control sends to 
{ID_FONTS, "Select Fonts" }, pear ete ne ve 

}: query the application for informa- 
: tion (WM_CONTROL), messages sent to 
case WM_COMMAND: notify the application of significant 
if (SHORTIFROMMP(mp2) == CMDSRC_MENU) { /* From the PM menu +/ events (WM_CONTROL), and messages 
/* IDs of PM menu — Hs fixed me values +/ sent by the application to the 
TtemID = SHORTAFROMMP(mp1) ; * Extract item ID +/ ds : 
WinSendMsg(hwnd, WM_USER+1, /* Send myself msg to do it */ mie or set various 
MPFRONSHORT(ItemID), OL); ae 
} UCMENUS DATA STRUCTURES 
ves Two primary data structures are 
case WH_CONTROL: related to UCMenu controls. 
if ( (SHORTIFROMMP(mp1) == ID_TOOLBAR) && Associated with each UCMenu 
(SHORT2FROMMP (mp1) == UCN_ITENSELECTED)) { window is a set of data that de- 
if (ItemData->pszAction == NULL) /* Ignore if no action */ scribes various aspects of the 
return 0; overall toolbar appearance and 
/* Lookup action of this item and map to fixed ID_XXXX value */ behavior. This includes informa- 
/* then send myself a message to process it. +/ tion such as style flags, menu col- 
for (i=0; i<MAX_ACTIONS; i++) { ors, and text font. This is the 
if (!strompi(ActionTable.Action[i] , ItemData->pszAction)) { UCMINFO structure shown in Figure 
Peseeeens Kt, NB_USESL; 7. It is filled in by the application 
MPFROMSHORT (ActionTable.CmdID), OL); ae 
para 0: and used during creation of a 
} UCMenu control. 
} Associated with each item of 
WinMessageBox(...error, action not recognized...); the menu are two linked data 
return 0; structures, as shown in Figure 8. 
} The first is the standard 
Presentation Manager MENUITEM 
structure. That structure contains 
case WH_USER+1: /* Process selections from any menu */ an “item handle” that is generally 
switch (SHORTIFROMMP(mp1)) { reserved for application use. A 
sat oats I do clipboard copy UCMenu uses the item handle to 
Aceiines indo: Chighoard paste point to a UCMITEM structure, which 
praal provides UCMenu-specific item in- 


case ID_LJUSTIFY: // do justification formation. In effect, the MENUITEM 


break: structure is extended for UCMenu- 
case IDFONTS: // do font selection specific data. It should be noted 
break; that any of the string pointers in 

} the UCMITEM structure can be null. 
return 0; These data structures are used 


extensively in the processing of 
messages to and from the 
Figure 5. Method to combine Presentation Manager and UCMenu selection processing. UCMenu control. 


54 OS/2 DEVELOPER 


Checkable Menu Items. The fact that 
a UCMenu can be extensively cus- 
tomized by the user has some im- 
portant implications for applica- 
tions with “checkable” style menu 
items. Like a Presentation Manager 
menu, any item in a UCMenu can 
be checked simply by setting the 
MIA_CHECKED attribute for that item. A 
menu item should be checkable if 
the action associated with it repre- 
sents the toggling of some applica- 
tion state. A checked menu item is 
indicated in a UCMenu by draw- 
ing a thick border around it. 

When a UCMenu item is cre- 
ated by the user, the MIA_CHECKED at- 
tribute is not set. Thus, if the action 
selected by the user for the new 
item is a toggle function, the appli- 
cation should update the current 
state of the item with the current 
state of the application. 

Likewise, when a menu item is 
modified and assigned a new ac- 
tion, the current attributes are not 
changed. If the new action is a tog- 
gle function, the item attribute 
must be updated to reflect the cur- 
rent application state. If the action 
is not a toggle function, the 
MIA_CHECKED attribute should be 
cleared since the previous action 
may have been checked. 

The UCMenu control will send Figure 6 Summary of UCMenu messages. 
a WM_CONTROL message with a notifi- 
cation code of UCN_ADDEDITEM or 
UCN_ACTION when a new item is 
added or an action is changed. 
When these messages are received, 
the application must examine the 
new action and set or clear the 
MIA_CHECKED attribute. The code in 
Figure 9 shows the processing of 
this message. Note that we have 
expanded the table used in Figure 
5, which maps actions to fixed IDs, 
adding flags to determine if a par- 
ticular action is supposed to be 
checkable and to track its check 
state. 

When the application is noti- 
fied of a selection on a checkable 
UCMenu item, it must toggle the Figure 7. UCMINFO structure describing general characteristics of a UCMenu. 
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as check state. In a standard Pre- menu item selected. Since a same menu, the check state of all 
y= sentation Manager menu, it is suf- UCMenu may have the same (tog- items with the toggle action must 
—! ficient to toggle the state of just the gle) action on different items in the be updated. 

This function has been incor- 
porated into the UCMenu API set 
with the function UCMenuSet- 
ActionAttr(). This API will set the 
attributes of all items in the 
UCMenu with the specified action 
string. If the application has multi- 
ple UCMenu toolbars, all must be 
updated since the action may exist 
in any of them. 






Customization Messages. Easy cus- 
tomization of the toolbar is one of 
—___—! the most useful and powerful fea- 
Figure 8. UCMenu item data structures. tures of this control. It gives the 








Move menu items Drag and drop menu items from one position to another. New position 
will be insertion point nearest the mouse cursor when the item is dropped. 
MIS_SPACER items can also be moved. Items may be moved from one toolbar 
to another. 


Copy menu items Drag and drop menu items with the Ctrl key pressed. Items may be 
copied from one toolbar to another. 


Copy to submenu Drag menu item with Alt key pressed and drop on another menu item. If 
the target item is not a submenu it will be changed to be one. The dropped 
item is inserted after the last item already in the submenu. Submenu items 
can be copied from one toolbar to another. 


Delete menu items Drag menu item to system shredder. 


Create new items Drag .BMP file type from desktop or drives folder onto a toolbar. A new 
item with the supplied bitmap will be created. The item will not have any 
text or action associated with it until provided with the context menu ‘Edit 
item’ option. 


Render bitmap to file A menu item that has file-supplied bitmap (the bitmap specification is a 
| file name, not an application resource) can be dragged to the OS/2 desk- 
top or a folder to create a .BMP file. The bitmap can also be dropped on the 
OS/2 Icon Editor desktop object to open and edit the source bitmap file. 


Change colors A color can be dragged from the system color palette onto the toolbar 
background or the item background. All items will have the same back- 
ground color. 

Change font A font can be dragged from the system font palette onto the toolbar. The 


dropped font will be used for the text under the bitmaps. 


Items can also be created, deleted, and edited with the context menu, which may be displayed by positioning the cur- 
sor on a menu item and pressing the right mouse button. 


Table 1. Direct manipulation capabilities of UCMenu toolbars. 
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user complete flexibility to add 
and delete menu items, rearrange 
the order, create submenus, and 
move and copy items between 
toolbars. Encapsulation of these 
functions into the UCMenu control 
means that there is very little ap- 
plication code required to support 
customization. 

Although most of the cus- 
tomization function is encapsu- 
lated in the control itself, the ap- 
plication must respond to several 
messages for customization to 
work properly. The UCMenu con- 
trol will send WM_CONTROL messages 
to its owner when it needs certain 
types of information to present 
on the customization notebook 
dialogues. The WM_CONTROL notifica- 
tion codes for customization are 
as follows: 

e UCN_QRYDEFAULTID: This is sent 
when the user selects the Load 
default context menu item to re- 
store the entire UCMenu to its 
default configuration. The appli- 
cation responds by supplying 
the resource ID of the menu tem- 
plate to be loaded. 
UCN_QRYTEMPLATEMODULE: This is also 
sent when the Load default con- 
text menu item is selected. The 
application must supply the 
handle of the module in which 
the UCN_QRYDEFAULTID resource is to 
be found. 
UCN_QRYRESBMP: This message is 
sent when the user wants to dis- 
play a list of application-sup- 
plied bitmaps from which to 
choose. The application must al- 
locate and construct an array of 
bitmap resource IDs. 
© UCN_QRYACTIONLIST: This message is 
sent when the user has re- 
quested a list of actions from 
which to choose. The application 
responds by sending a series of 
UCMENU_INSERTACTION messages, 
each with a pointer to an action 
string and descriptive help text. 
After the last action has been in- , = 
serted, the application must Figure 9. Setting “checked” attribute on added and modified UCMenu items. 
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send UCMENU_ACTIONSINSERTED to in- 
dicate the list is complete. 

e UCN_HLP_#: This is a set of mes- 
sages sent when the UCS_CUSTOMHLP 
menu style is used and the user 
requests help on a customization 
dialogue. By default, the 
UCMenu control will supply the 
needed help text. 

The handling of all these mes- 
sages is demonstrated in the 

SAMP2.C sample program. 


CONTROL OF CUSTOMIZATION 

The highly flexible customization 
built in to the UCMenu control 
may not be desirable for all appli- 
cations or situations. For example, 
the ability to move items from one 
menu to another within an appli- 
cation may not make semantic 
sense. An application with multi- 
ple windows performing different 
functions may not want to allow 
the user to drag items from the 





Moving Menu Items 
UCS_NO_DM_M_TO_OTHER 
UCS_NO_DM_M_FROM_OTHER 


UCS_NO_DM_M_FROM_INSIDE 


Disable drag-move of items to another UCMenu 

Disable drop-move of items from another 
UCMenu 

Disable drag-drop move (rearrangement) of 
items inside this UCMenu 


Copying Menu Items (CTRL key drag/drop) 


UCS_NO_DM_C_TO_OTHER 
UCS_NO_DM_C_FROM_OTHER 


UCS_NO_DM_C_FROM_INSIDE 
UCS_NO_DM_ALT 

Desktop Interaction 
UCS_NO_DM_DISCARD 
UCS_NO_DM_RENDER_TO_BMP 
UCS_NO_DM_RENDER_FROM_BMP 


Context Menu Control! 
UCS_NO_CM_MENU_STYLE 


UCS_NO_CM_MENU_IMPORT 
UCS_NO_CM_MENU_EXPORT 
UCS_NO_CM_MENU_DEF AULT 


UCS_NO_CM_ITEM_CREATE 


UCS_NO_CM_ITEM_DELETE 
UCS_NO_CM_ITEM_EDIT 


Combination Styles 
UCS_NO_DM 

UCS_NO_CM 
UCS_STATIC 


Disable drag-copy of items to another UCMenu 

Disable drop-copy of items from another 
UCMenu 

Disable drag-drop move (rearrangement) of 
items inside this UCMenu 

Disable use of ALT key to copy items to 
submenus 


Disable drag of items to system shredder to 
delete them 

Disable drag of items to desktop to create .BMP 
files 

Disable drop of .BMP files to create new items 


Remove “Change style...” option from context 
menu 

Remove “Import...” option from context menu 

Remove “Export...” option from context menu 

Remove “Load default” option from context 
menu 

Remove “Create item...” option from context 
menu 

Remove “Delete item” option from context menu 

Remove “Edit item...” option from context menu 


Disable all direct manipulation 

Disable context menu 

Disable all direct manipulation and context 
menu 


Table 2. UCMenu customization style flags. 
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toolbar in one window to the tool- 
bar in another. The result might be 
actions that make no sense in the 
context of the window. The appli- 
cation may also want to provide its 
own customization methods to re- 
place or supplement those of 
UCMenus. 

By default, all the direct ma- 
nipulations shown in Table 1 and 
all the context menu options 
shown in Figure 2 are allowed. 
Various style flags (UCS_*) can be 
used by the application to control 
which direct manipulation and 
context menu functions are sup- 
ported for that instance of the 
menu. At the extreme, the applica- 
tion can set a style of UCS_STATIC to 
prevent any customization at all. 
This style will disable all direct 
manipulation functions and the 
context menu. Other style flags 
allow selective disabling of specific 
customization functions, such as 
disabling drag-and-drop between 
menus (but allowing it within a 
menu), disabling drops to the sys- 
tem shredder, removing the “Edit 
item...” context menu option, and 
so on. Table 2 summarizes the cus- 
tomization style flags. 

An application can also supply 
its own customization functions 
via the UCMenu context menu. By 
sending the control a UCMENU_AD- 
DITEMSTOCM message, the application 
can add its own options to the con- 
text menu. The UCMenu control 
will send a WM_CONTROL message with 
a notify code of UCN_CMITEM when 
such an option is selected. A sam- 
ple of adding an application cus- 
tomization function to the context 
menu is shown in Figure 10. 


CREATING A UCMENU CONTROL 

Conceptually, creating a UCMenu 
control is the same as creating a 
Presentation Manager menu con- 
trol. The menu structure and items 
are defined in textual form in a re- 
source file (.RC) using MENU, MENUITEM, 
and SUBMENU statements. The re- 


source file is compiled with the re- 
source compiler into binary re- 
source format and appended to the 
application executable (or a DLL). 
The application calls an API to read 
the binary resource and create the 
visual Presentation Manager win- 
dows and underlying data struc- 
tures. Finally, the window is placed 
and sized on a parent window. 


Resource Files. The textual resource 
file specifies the complete structure 
of the menu and the contents of 
the menu items. However, the MENU- 
ITEM resource statement does not 
have the syntactic flexibility to 
allow complete specification of all 
the data associated with a UC- 
Menu item. Therefore, the text 
field of the MENUITEM statement is in- 
terpreted to contain four extra 
fields of information not found on 
standard Presentation Manager 
menu items: bitmap specification, 
action string, parameter string, and 
a data string. Each of these fields is 
separated by a single character de- 
fined as the first character of the 
string. A typical resource file for a 
UCMenu is shown in Figure 11. 
Some notes on UCMenu re- 
source files: 
¢ The menu item [Ds specified in 
the resource file are arbitrary. 
Sequential numbering is used to 
help keep menu items unique 
but is not necessary. 
eA new menu item style 
MIS_SPACER is defined for 
UCMenus. It produces a blank 
space in the menu to separate 
menu items into groups. 
¢ The ‘Data’ field is not seen by the 
user and is for application use. 
Note that new items created by 
customization will have no 
‘data’ value. 


The UCMINFO Structure. To complete 
the process of creating a UCMenu, 
the application must construct a 
UCMINFO data structure (as shown in 
Figure 7) and fill in all the relevant 





Figure 10. Adding an option to the UCMenu context menu. 


fields. The RGB values of the struc- 
ture are used for color mapping 
the bitmap background pixels. 
UCMenus supplies a means for 
bitmap background pixels to be 
automatically mapped to the cur- 
rent UCMenu background color. 
The BgBmp value of UCMINFO tells 
UCMenus what background color 
was used in the design of the 
bitmaps. That color will be re- 
placed with the ItemBgColor before 
the bitmaps are displayed wher- 
ever that color appears in the 
bitmap. The ItemBgColor should be 
set to the SYSCLR_MENU color returned 
by WinQuerySysColor(). A different 
color may be specified in the 
BgColor field. This will be the color 
used wherever there are no items 
on the toolbar. 

Once the UCMINFO structure is 
filled in, the — function 
UCMenuCreateFromTemplate() or 
UCMenuCreateFromResource() is called. 
The template version is used if the 
application has manually loaded a 
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previously saved UCMenu tem- 
plate. The resource version will 
create a UCMenu from a menu 
template in the application’s re- 
sources. The parameters are shown 
in Figure 12. The creation functions 
return two window handles. The 
function result is the window han- 
dle of interest for the application; 
the other may be ignored. 


PLACEMENT AND SIZING 

OF A UCMENU 

Toolbars are generally placed 
along one edge of the application 
window frame. Toolbars may be 
attached to the top, bottom, left, or 
right edge of the window, Figure 1 
shows a frame window with four 
toolbars, one on each edge of the 
frame. 

It is possible to simply place 
and size the toolbar into the client 
window of a standard Presentation 
Manager window. However, this 
simple approach introduces a lot of 
complexity when the application 
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BITMAP 6 "new. bmp" 
BITMAP 1 "open. bmp" 
BITMAP 2 “save. bmp" 
BITMAP 62 "styles. bmp" 
BITMAP 63 "bold. bmp" 
BITMAP 64 "italic. bmp" 


BITMAP 8 “help. bmp" 

/* Text strings are interpreted as: #/ 
; "<coText<coBitmapID<c>ActionStr<coParamStr<c>DataStr" 
5 where <c> is any character that does not appear in the strings. 7 
i Ttem style MIS_SPACER produces a gap in the menu bar. z 


MENU ID_COMMANDBAR LOADONCALL MOVEABLE DISCARDABLE 


BEGIN 
MENUITEM "/New/6/New", 
MENUITEM "/Open/1/Open File", 
MENUITEM "/Save/2/Save File", 
MENUITEM "", 
SUBMENU "/Styles/62/Styles Submenu", 
BEGIN 


1, MIS_TEXT 
2, MIS_TEXT 
3, MIS_TEXT 
4, WIS_SPACER 
5, MIS_TEAT 


/* Use a different delim here so ve can use "/" in the strings +/ 


MENUITEM "!Bold!63!Bold/Style", 
MENUITEM "!Ttalic!64!Italic/Style", 
END 
MENUITEM "", 
MENUITEM "/Help/8/Show Help", 
END 


6, MIS_TEXT | MIS_CHECKABLE 
7, MIS_TEXT | MIS_CHECKABLE 


8, MIS_SPACER 
9, MIS_TEXT 


Figure 11. Resource file statements for a UCMenu. 


must properly scale and paint the 
client window. If the frame win- 
dow is a dialogue, proper size and 
placement is even more complex 
since the application does not 
paint and there is no separate 
client window. 

The proper solution to toolbar 
placement is to make the toolbar a 
frame control. A frame control is a 
child of the frame window and par- 
ticipates in a special message proto- 
col. Standard frame controls include 
the title bar, scroll bars, Presentation 
Manager menu bar, min/max but- 
tons, and the system menu. The 
frame controls move and size with 
the frame window and keep proper 
position in the frame through the 
frame control messages. 

Making a window into a frame 
control requires a thorough knowl- 
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edge of how Presentation Manager 
frame windows and message proto- 
cols work. Adding a frame control 
to a dialogue window is even more 
complex since it may require the 
movement of all the dialogue con- 
trols. All the functions necessary to 
make UCMenu windows into 
frame controls are supplied in a set 
of utility routines in the toolkit. 
These routines are not a formal part 
of the UCMenu control but allow 
an application to easily place 
UCMenu controls along any edge 
of a frame or dialogue window. By 
using these utilities, an application 
can be completely removed from 
any sizing or positioning considera- 
tions for the toolbars. 

The frame control utilities con- 
sist of two functions: one to add a 
UCMenu to a frame or dialogue 


OS/2 DEVELOPER 


window, the other to remove it. 
The UCMUtils() functions are shown 
in Figure 13. The utilities support 
up to four toolbars per frame or di- 
alogue window (one each at the 
top, bottom, left, and right edges). 
By calling the add/remove frame 
control utilities, a toolbar can be 
toggled on and off. 

The UCMUtils() functions encap- 
sulate all the complexity of frame 
control management, freeing the 
application from that task. With 
just a simple function call, the tool- 
bar can be positioned in the frame 
and will maintain its proper posi- 
tion as the frame is sized and 
moved. Source code for the utili- 
ties is provided in the toolkit. 


A DYNAMIC STATUS BAR 

One drawback to graphical menu 
bars is the cryptic nature of the in- 
formation presented. Even the 
most creative bitmaps can fail to 
convey the meaning of a function. 
Text under the bitmap, as allowed 
by UCMenus, helps the user 
quickly understand the functions 
on the toolbar. However, even that 
may not be enough for the casual 
user to grasp the meaning of a 
graphic menu item. 

A dynamic status bar can be 
implemented by the application to 
automatically show a description 
of each menu item as the mouse 
pointer is moved on the toolbar. To 
help the application implement 
this feature, a UCMenu with the 
UCS_PROMPTING style will send WM_CON- 
TROL messages with a notify code of 
UCN_MOUSEMOVE when the pointer 
moves on the menu bar. The mes- 
sage supplies the menu item ID of 
the item under the mouse pointer. 
Using this item ID, the application 
can obtain the item data structures 
and determine the action string as- 
sociated with that item. The action 
string may be displayed directly, 
or it may be used to look upa 
more complete description for dis- 
play to the user. The SAMP2.C 


sample program uses the lookup 
method to display a longer de- 
scription of the menu items action. 


SAVING/RESTORING UCMENUS 
When an application with cus- 
tomizable menus is closed and 
restarted, the user expects the 
menus to resume their customized 
state. The application must save 
the complete state of the UCMenus 
when closing, including the menu 
attributes in the UCMINFO structure 
and the actual menu item structure 
(order of items, text, bitmaps, ac- 
tion strings, and so on). 

The UCMenus API provides 
several functions to aid the applica- 
tion in saving and restoring the cus- 
tomized state of UCMenu toolbars. 
The function UCMenuMakeTemplate() 
will create a binary in-storage rep- 
resentation of the complete UC- 
Menu item structure. The binary 
image will include all text, 
bitmaps, action strings, and ar- 
rangements of menu items. The cor- 
responding APIs, UCMenuCreate- 
FromTemplate() and UCMenuNew, create 
and replace UCMenu controls from 
an in-storage binary template. 

Figure 14 shows the processing 
of WM_SAVEAPPLICATION for the 
SAMP2.C sample program. This 
sample has two UCMenu toolbars, 
but for brevity, the code for only 
one is shown. The UCMenu style, 
colors, and font, as well as the bi- 
nary templates, are stored in the 
application .INI file. During initial- 
ization, the styles, colors, font, and 
templates are read from the .INI 
file and are used to recreate the 
customized toolbars. 


SUMMARY 

The UCMenu control provides a 
powerful, slick-looking, and easy- 
to-use toolbar control for OS/2 
Presentation Manager applica- 
tions. The encapsulation of exten- 
sive customization capabilities 
gives application writers a power- 
ful, customizable toolbar with min- 


imal code. For the user, UCMenus 
provides an easy-to-use toolbar 
that is simple to customize with in- 
tuitive drag-and-drop and context 
menus. 

Examination of the SAMP2.C 
sample program shows how a typ- 





Figure 12. Seclected UCMenu APIs. 


ical application might be struc- 
tured with respect to menus and 
menu selection processing. The 
sample shows the usage of most of 
the UCMenu-specific messages 
and fully implements all features 
of the UCMenu control. 








Figure 13. Frame control management utility functions. 
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np a 
/* Structure to easily save/restore menu information in INI file +*/ 


typedef struct { 
ULONG CmdStyle; /* Command menu style bits */ 
ULONG CmdCx; /* Forced size (x) +/ 
ULONG CmdCy ; /* Forced size (y) */ 
ULONG CmdSize; /* Size of menu template +*/ 
ULONG CmdBgColor ; /* Toolbar background */ 
ULONG CmdItemBgColor; /* Item background */ 
char CmdFont(32];  /# Font name +/ 

} IniDataStruct; 

BOOL ProfileFound = FALSE; /* INI file existed +/ 

UCMINFO UCMInit; /* UCMenu creation data +/ 

PVOID CmdTemplate; /* Ptr to menu template +*/ 


HWND © CommandBar ; /* UCMenu window handle +/ 


WM_CREATE: // (or WM_INITDLG, if a dialog): 


/* If we have saved a previous UC menu configuration in the .INI +*/ 
/* file, restore its contents and style information. */ 


IniHandle = PrfOpenProfile(Hab, "myapp.ini"); 
if (IniHandle != NULLHANDLE) { 
/* If one value is here, they all should be +/ 
ULValue = sizeof (IniDataStruct) ; 
if (PrfQueryProfileData(Initandle, "APPNAME", 
"IniData", &IniData, &ULValue)) { 
CmdTemplate = malloc(IniData.CmdSize) ; 
PrfQueryProfileData(IniHandle, "APPNAME", "CmdTemplate", 
CmdTemplate, &(IniData.CmdSize)); 
ProfileFound = TRUE; 
} 
PrfCloseProfile(Initandle) ; 
} 


// Initialize all fields of the UCMLinit structure here...then: 

if (ProfileFound) { /* Create menu from saved template */ 
UCMInit.Style = IniData.CmdStyle; /* Restore menu style */ 
UCMInit.cx = IniData.CmdCx; /* Restore forced size */ 
UCMInit.cy = IniData.CmdCy; /* Restore forced size */ 
UCNInit..BgColor = Inidata.CmdBgColor; /* Colors */ 
UCMInit.ItemBgColor = IniData.CmdItemBgColor:; 
UCMInit.pszFontNameSize = Inibata.CmdFont; /* Font */ 
CommandBar = UCMenuCreateFromTemplate(...CmdTemplate...); 
free(CmdTemplate) ; 

} 

else { /* Create menu from resource file */ 
CommandBar = UCMenuCreateFromResource(...ID_TOOLBAR...); 

} 


WM_SAVEAPPLICATION: 


/* Create incore template representation of the menu */ 
CmdTemplate = UCMenuMakeTemplate(CommandBar, &(IniData.CmdSize)) ; 
/* Open INI file and save template and style info */ 

IniHandle = PrfOpenProfile(Hab, "myapp.ini"); 

if (IniHandle != NULLHANDLE) { 


Figure 14. Saving and restoring a customized toolbar in the application .INI file (continued on page 63). 
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PrfWriteProfileData(IniHandle, "APPNAME", “CmdTemplate", 


CmdTemplate, IniData.CmdSize) ; 


/* We must also save the style bits, size, colors, fonts. */ 
/* Colors and fonts can be modified via system palettes. */ 
WinSendMsg(CommandBar, UCMENU_QUERYUCMINFO, MPFROMP(&UCMInit), OL); 


| 
IniData..CndStyle 
| 


= UCMInit Style; 
Inidata.CmdCx = UCMInit.cx; 
IniDdata .CmdCy = UCMInit.cy; 
 ‘IniData.CmdBgColor = UCMInit.BgColor ; 
 Inidata.CmdItemBgColor = UCMInit . ItemBgColor ; 


if (UCMInit.pszFontNameSize != NULL) 


-strepy(IniData.CmdFont, UCMInit.pszFontNameSize) ; 


else (IniData.CmdFont) [0] = “\0’; 
UCMUtilsFreeUCMInfoStrings(&UCMInit) ; 


PrfWriteProfileData(IniHandle, "APPNAME", "IniData", &IniData, 
sizeof (IniDataStruct)); 


PrfCloseProfile(IniHandle) ; 
4} 
UCMenuFree(CmdTemplate) ; 
UCMenuFree(ClrTemplate) ; 
break; 


Figure 14. Saving and restoring a customized toolbar in the application .INI file (continued from page 62). 
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This article provides a brief overview of things to keep in mind when developing applications for OS/2. 
By DIETER BABUTZKA 


An OS/2 Performance 


Primer 


uring the development of a 
D new application, performance 

isn’t always given the attention 
it deserves, particularly in the early 
phases of a project. This article re- 
views some basic guidelines that 
should help improve your OS/2 appli- 
cation’s performance. 


PROCESSES AND THREADS 

A large number of processes and 
threads in your application generate 
overhead from process and thread 
switches. It makes sense to use multiple 
processes and threads only when they 
can run independently or are used for 
protection reasons. Process switches con- 
sume more time than thread switches. 
Use multiple threads only if the applica- 
tion consists of parts that are able to run 
concurrently. Multiple processes should 
be used to prevent accidental overwrit- 
ing of memory and to be completely in- 
dependent of other parts of the applica- 
tion (crash protection). 


FUNCTION CALLS 

Although it may be fashionable to create 
a lot of very small functions, this can 
lead to performance problems since 
there is a significant overhead for func- 
tion calling. It is important to avoid a 
high number of calls from 16-bit to 32- 
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bit applications because this leads to a 
perceptible overhead. 


HOST OR LAN CALLS 

Most newly developed applications are 
not stand-alone but work in a client/ 
server environment. It is important to 
keep the number of interplatform calls 
to a minimum because every communi- 
cation step generates an overhead that 
leads to longer response times. 


MEMORY CONSUMPTION 

In a modern OS/2 environment, there is 
almost unlimited virtual storage avail- 
able for every application. But using a 
large amount of storage reduces not only 
the speed of your application but also the 
storage available for other applications, 
so their speed is also reduced. Try run- 
ning the code example in Figure 1 while 
running another application, You'll no- 
tice that the whole system is much less 
responsive. Be careful! This program will 
use up to 40 MB of memory, and eventu- 
ally your swap drive will be full. 





DYNAMIC LINK LIBRARIES 

The use of DLLs makes a lot of sense be- 
cause the storage used for the whole 
system can be reduced. To reduce load- 
ing times, the number of DLLs should 
not be too large. We were able to reduce 
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startup time more then 10% after 
we reduced the number of DLLs 
from 20 to only one. 


DATA FILTERS AND DATA 
CONVERSION 

Sometimes much more data is 
transferred from a server to a client 


than is really used. This should be 
avoided by using data filters at the 
first possible point, usually on the 
server. Often, the data is converted 
many times before it reaches the 
user. Try to convert data only once. 
Following is a typical example of 
the usefulness of a data filter. Let's 
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/* SPMTEST2 (program for SPM/2) +/ 
/* Just consumes RAM +/ 
/* It allocates every 0.5 sec. 40kB of memory, up to 40 MB +/ 
[+ */ 
/* COPYRIGHT: +/ 
[$ o-~-<<---- +/ 
/* Dieter Babutzka Boeblingen Software Systems 03.08.93 */ 
/* */ 
/ KEKEERERESEEEEEEEE EHS EES $AKAAAEAAA EAA RARE ARARARAAEREAARELESEREEEER REE EES / 
/* */ 
/* NOTE: The program also requires the IBM TOOLKIT 2.0 headers +/ 
[* */ 
SEE ERE EERE AE IAAI AE AIRE R TATE A IA ARR AA/ 
#define INCL_DOS 

#define INCL_DOSMEMMGR 

#include <os2.h> 


#include <malloc.h> 
#tinclude <bsememf .h> 
#include <process.h> 
#include <stdio.h> 
#include <stdlib.h> 


int main( int argc, char *argv’ ) 
{ 

PVOID memadd=NULL ; 

ULONG size=40000; 

PCHAR help=NULL; 

int i=0; 


/* Do nothing, but just consuming memory */ 


i=0; 

for (i=1;i<1000;i++) { 
DosAllocMem(&memadd,size, f 
ALLOC); help = 
(PCHAR)memadd ; 
memset (memadd, “\0° ,size); 


strepy(help,"I’m a memory eater!"); 


DosSleep(500) ; 
} /* endfor */ 
return; 


} 


Figure 1. Code example for an OS/2 application allocating a large amount of memory. 
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say you work on an OS/2 machine 
with a host database as a server 
and want to get data from this 
database. The database should 
consist of a large number of data- 
base objects. If you want to get all 
objects where the object name 
starts with an A, you'll have 
mainly two options: 

* Get all objects from the host and 
look for all objects where the ob- 
ject name starts with an A. 

¢ Pass a filter to the host and cap- 
ture only these objects from the 
database where the object name 
starts with an A. 

Normally, the data has to be 
converted in the object format de- 
fined on the workstation. Try to 
keep this conversion as easy as pos- 
sible—meaning the organization of 
the objects on the workstation 
should not differ too much from the 
implementation on the host. 


APPLICATION BUILDERS 

An application builder makes 
sense in the development of large 
applications. For a small project, 
an application builder may not be 
advisable because it generates too 
much overhead. 

During the coding process, it is 
important to ensure the perfor- 
mance of an application (or of se- 
lected key sections) by using test 
scenarios. These scenarios should 
be defined during the design phase, 
and if possible, goals should also be 
specified. Attention should be paid 
to mainly two items. 


Path Length. Every developer 
should use a software performance 
analysis utility to measure the run 
time and the active time of a com- 
ponent, such as EXTRA. EXTRA is 
an abbreviation for the IBM 
C/C++ Execution Trace Analyzer. 
EXTRA is part of the IBM C Set++ 
compiler, but other performance 
analysis applications are also avail- 
able for many other compilers. 
With EXTRA, you can analyze the 


run time, the active time, the num- 
ber of calls, and who is called by 
whom. 

Figure 2 shows the statistical 
output of EXTRA for a test program. 
You'll get information about the ac- 
tive modules (EXEs and DLLs) and 
a lot of details about the function 
called during the test scenario. 

This is very important in com- 
plex systems coded in object-ori- 
ented programming languages. In 
this environment, it may not be 
known which calls occur and how 
often the various methods are 


called. 


Memory Consumption. Although in 
the OS/2 concept a lot of virtual 
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memory is available for every ap- 
plication, you have to keep in 
mind that only a limited amount of 
real storage is available. We use the 
IBM SPM/2 2.0 product to check 
memory allocation. 

With THESEUS/2, which is 
part of SPM/2, you can determine 
the memory used in various alloca- 
tions (Decommitted, Committed, 
Accessed, Present, Swapped out). 
It can also be determined when an 
application allocates memory and 
does not free it again. This is not a 
real problem if the process to 
which this program belongs termi- 
nates. But if the program works as 
a server, which is designed to run 
continuously, it is very important 


AXTRA\GOS.EXE run 10/28/94 at 04:10:01 PM 


d6% ENATRA\GOS.EXE 
64% EAXTRA\BUSGOSAIDLL 


Executables generating events: 2 of 27 


Functions generating events: 74 


Function Names 


main 
ResCreateBitmapOfPS.BUSGOSAI 
FntSetAttr.BUSGOSAI 
ResCreateMemHPS.BUSGOSAI 
GosMainCreateViewportWindow 
GoslnitLogFiles.BUSGOSAI 
| Gosinit. BUSGOSAI 
LogString.BUSGOSAI 
FraQpenBitmapFile.BUSGOSAI 
GosinitGlobal. BUSGOSAI 


DOMEMOFLLBUSU - 


Figure 2. Statistical output of EXTRA for a test program. 


% Run | % Active | Total Calls 
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to look for memory that needs to 
be freed. This can slow down per- 
formance dramatically. 

Figure 3 gives a short view 
about the actual memory division 
of all running programs. This is 
not the working set of the program 
but primarily a snapshot of the 
memory. 

Although EXTRA helps in 
finding application bottlenecks, it 
is important to measure perfor- 
mance test scenarios with accurate 
precision. To do this, it is impor- 
tant to measure with as little over- 
head as possible. EXTRA and other 
software tools normally operate on 
debugging and nonoptimized 
code, so loading and startup times 





_§ 
Active Time 
7.980 fl 


Run Time 


2,080 
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are higher than in production 
code. 

The tool we used to make this 
measurement accurately while 
generating litthe overhead was an 
IBM internal hardware tool. It is 
possible for IBM customers to bor- 
row this hardware to analyze ap- 
plications. Performance analysis is 
also available as an IBM service of- 
fering, which is available through 
the author. 

When using this tool, hooks 
are written to a special card and 
transferred to another machine for 
analysis after the test scenario has 
finished. 


Through the help of a software 
tool, hooks are included automati- 
cally at the beginning and the end 
of each function. After the execu- 
tion of the test scenario, informa- 
tion is available for each function, 
consisting of: 

* A trace listing showing when 
each function was called, who 
called it, and how long it was 
active 

e Statistics about the active and 
idle periods (for example, wait- 
ing for an event, host communi- 
cations, and so on) 

© Statistics about each observed 
function, how often it was 


called, time spent in each func- 
tion, and the overall run time. 
With this data, it is not difficult 
to find the bottlenecks of an appli- 
cation, although they still have to 
be fixed. 
Some additional considera- 
tions should be kept in mind: 

e Even a hardware test tool has 
some overhead—usually around 
2%. But this overhead is sub- 
tracted from its measurement, so 
its accuracy is very high. After 
the overhead is subtracted, the 
difference between instrumented 
and noninstrumented measure- 
ments is less than 1%. 





Usage by Process: 





Sse 5=*eS OP ESEte reessees) esas owned shared ------ 

bytes Kbytes Mbytes bytes Kbytes Mbytes who 
j0677000 68666 6.465 00219000 2146 2.098 system 
90000000 0 0.000 sysinit 
p0000000 0 0.000 00002000 8 0.008 LANMSGExX 
y0000000 0 0.000 LANDLL 
10006000 24 0.023 CNTRL 
I003A000 232 0.227 OOOEGOO00 920 0.698 PMSHL32 
s0000000 0 0.000 HARDERR 
j0000000 0 0.000 00010000 b4 0.063 STOPLAN 
70064000 400 0.391 00037000 220 0.215 PMSHL32 
p0000000 LL) 0.000 CMD 
90014000 104 0.102 00006000 24 0.023 PMD | ARY 
y000A000 40 0.039 00001000 4 0.004 TIMEXEC 
y0000000 0 0.000 00006000 24 0.023 CMSTART 
900710000 64 0.063 00040000 256 0.250 CMD 
90000000 0 0.000 EPWROUT 
y0000000 0 0.000 EPWHUX 
y0000000 0 0.000 ACSRASP 
90001000 4 0.004 00013000 76 0.074 ASPOOO 
p000D000 52 0.051 00005000 20 0.020 CMKFMSH I! 
p0000000 0 0.000 MUGLR@ST 
10040000 256 0.250 o009D000 626 0.613 ACSSEINI 
900710000 64 0.063 oo000c000 48 0.047 WKSTA 
p0000000 0 0.000 WKSTAHLP 
p0000000 0 0.000 LSCLIENT 
NOOCEOOO 56 0.055 00008000 32 0.031 MSRY 
p0005000 20 0.020 00008000 32 0.031 NETPOPUP 
bpoo000000 a) 0.000 CMD 
y0000000 i} 0.000 LSDAEMON 
0005000 20 0.020 YDM 
p0057000 346 0.340 00003000 12 0.012 E 
p003B000 236 0.230 00016000 108 0.105 CHD 

320 0.313 ooc0D000 52 0.051 THESEUS2 
10908 10.652 00491000 4676 4.566 total RAM in use 
412 0.402 free RAM 









JOFSFOO0 
< End of THESEUS2 
ne 


Figure 3. Snapshot of the memory. 


total of all RAM pages found (Pvt * Shr + Free) 


output @ 17:05:58 on 10-27-1394 > 
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¢ No programmer likes to put 
hooks into his code for perfor- 
mance measurements. Therefore, 
an automatic instrumentation 
program is available that puts 
the hooks into the code without 
any manual interaction. These 
hooks are then written to the 
hardware for later analysis. 

The conclusion of our experi- 
ence is that it is important to look 
at the performance during the de- 
sign phase because it is hard to im- 
prove performance when coding is 
nearly complete. 


Dieter Babutzka has been with /BM 
since 1989 and works as a Senior 
Associate in the Boeblingen Programming 
Laboratory. He has worked in several MVS 
programming, planning, and testing groups 
for products like HCD and RMF. On the 
workstation side, he was responsible for 
the performance analysis of several OS/2 
products. He received a diploma in physics 
from the Eberhard-Karls-University in 
Tuebingen in 1986. Dieter can be reached 
at dbabutzka@vnet.ibm.com. 















Take it from our customers. A recent 
survey determined that, by using 
Quadron communications de- 
velopment tools, they cut 

32% off their estimated de- , 
velopment time. 

Increase your efficiency 
Our development software allows 
you to shift communications tasks 
from the CPU on a PC toa specialized 
co-processor card that’s designed to 
handle them. You'll gain CPU inde- 
pendence and multiple high-speed 
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Applications everywhere 

Today, Quadron helps people man- 
age demanding applications like: 

@ Travel reservation 

@ Stock market data delivery 

@ Telecommunications switching 
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® Shop floor control. 
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Tools that get the job done 


We have off-the-shelf solutions 
for your common data trans- 
mission needs, and tools for 
custom situations. Select 
from HDLC/SDLC, Bisync, 
Async, X.25, LAP-B and cus- 
tom protocols. 
Your host PC can be an ISA (AT), 
EISA, or Micro Channel machine. You 
can run OS/2, DOS, AIX or UNIX. And 
perhaps best of all, you can port the 
co-processor code that you write from 
one operating system to another with 
little or no modification. 
Work faster & simpler 
Quadron software is easy to install, 
easy to use, and downright productive. 
Our high-level, C-language API 
makes your co-processor pro- 
gramming faster. The user 
manuals have numerous code 
examples to speed you on your 
way. And our support, should 
you need it, will serve up fast 
and accurate answers to your 
questions, whether they come in 
by phone, fax, or through our BBS. 
Act right away 
Does this sound like something you 
could benefit from? Contact us right 
now, 


€® Quadron 
209 East Victoria Street 
Santa Barbara, CA 93101 USA 
fax 805-966-7630 
phone 805-966-6424 
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This article illustrates using the APL2 programming language. By DAVID LIEBTAG 


Interactive PM 


Programming 


5/2’s Presentation Manager is 
large, powerful, and complex. 
Since it has nearly 600 Win and 
Gpi services, learning how to use it is a 
daunting task. However, many of the 
difficulties in learning Presentation 
Manager can be overcome by taking an 
interactive approach. 

When using a compiled language, 
the learning process requires that you 
have a working program before you can 
even start to work with OS/2 services. 
Obviously, it is a bit difficult to write a 
program using services you don’t yet 
know how to use. Furthermore, with 
each new service you want to learn how 
to use, you must write new code, recom- 
pile, and then try to understand what 
went wrong if it doesn’t work. These are 
expensive steps in an iterative learning 
process. 

When using an interactive develop- 
ment environment, you can try a service 
and immediately see its effects. You can 
change the service’s parameters and see 
what effects these changes cause. It is 
also easier to work with Presentation 
Manager messages in an interactive en- 
vironment. Simply being able to exam- 
ine the Presentation Manager environ- 
ment at any time is a tremendous 
learning aid. 

An interactive development envi- 





ronment makes it convenient to explore 
questions like, | wonder what happens 
if I change the contents of the options in 
an accelerator table entry? It also makes 
it easier to explore Presentation Man- 
ager’s less widely used but most power- 
ful facilities, such as arbitrary unit pre- 
sentation spaces and retained graphics. 
APL2 is a general-purpose program- 
ming language used in a wide variety of 
disciplines. APL2 is an interpreted lan- 
guage and provides an interactive appli- 
cation development environment. APL2 
for OS/2, also called APL2/2, includes 
an interface to Presentation Manager 
that can be used to interactively develop 
Presentation Manager applications. This 
article illustrates how you can easily ex- 
ploit some of Presentation Manager's 
most powerful facilities using APL2/2. 


THE APL2-PM INTERFACE 

The APL2/2 product’s several compo- 
nents include a language interpreter, a 
session manager, and an auxiliary 
processor, called AP145, that provides 
an interface to Presentation Manager. 
The session manager provides a win- 
dow through which you communicate 
with the language interpreter and 
AP145, APL2 components communicate 
by using a special class of variables 
called Shared Variables. A shared vari- 
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able is a piece of data that is common to 
or shared between two components. 

A separate Presentation Manager 
environment is managed for each vari- 
able you share with AP145. Each envi- 
ronment includes a separate thread and 
message queue. AP145 monitors these 
queues and dispatches their messages. 
Most messages are immediately dis- 
patched to the appropriate default win- 
dow procedure. Only messages specifi- 
cally requested by the application are 
processed in APL2. 

AP145 supports many OS/2 ser- 
vices, including most of the Ddf, Dev, Dos, 
Drg, Gpi, Prf, Spl, and Win services. 

To call a service, assign the shared 
variable an array containing the service 
name and any parameters required by the 
service. To retrieve the service’s return 
code, you reference the shared variable. 
Here is an example of calling a Win service 
and retrieving the service’s results: 


SV145~“WinShowWindow’ HANDLE TRUE 
(APRC OSRC CMD)~SV145 


Note: In APL2, a left-arrow symbol 
assigns the value on the right to the 
variable name(s) on the left. 

For comparison purposes, here is 
the analogous call in C: 


Re = WinShowWindow(HANDLE, TRUE) ; 


The APL2 and C methods both use 
the same Presentation Manager con- 
stants and service names that are docu- 
mented in the Presentation Manager ref- 
erence manuals, 

The differences are that APL2 al- 
lows you to call the service interactively, 
and it will run asynchronously. You can 
continue with other processing before 
referencing the shared variable. 

Each reference of an AP145 shared 
variable returns a three-element array. 
The first element is an auxiliary proces- 





sor return code, This code is zero unless 
an error is encountered, such as an in- 
correct number of parameters. The sec- 
ond element is the return code of the 
service. The third element is the service 
name and its parameters. Services can 
update their parameters, so the values 
may be different from those originally 
assigned, 


CREATING A WINDOW 

To demonstrate how AP145 can be used 
interactively, the following examples 
show how to create a simple window 
and draw some graphics. You can type 
these commands directly into the 
APL2/2 session manager and watch 
Presentation Manager process the ser- 
vice calls. 

First, share a variable with AP145 to 
establish a connection with Presentation 
Manager. The SVOFFER routine can be de- 
fined using an APL2 COPY command. 


)COPY 1 UTILITY SVOFFER 
145 SVOFFER “SV145° 


The first service to call is 
WinRegisterClass to register a class for a 
window that you can work with. The 
CS_SIZEREDRAW variable, and the other Pre- 
sentation Manager constants used in this 
article, can be set using a COPY command. 


)COPY 2 PMWIN CS_SIZEREDRAW 
CLASS~“APL2 Client Class” 
STYLE~CS_SIZEREDRAW 


SVi45~"WinRegisterClass” 0 CLASS 0 STYLE 0 


Now, call WinCreateStdWindow to create 
a standard frame window, as shown in 
Figure 1; for the client class, use the class 
name you just registered. This will cause 
a standard window to appear on your 
desktop. 

The FCF_SHELLPOSITION flag causes 
your window to be created with a stan- 
dard position and size. However, it does 
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Figure 1. Calling WinCreateStdWindow to create a standard frame window. 


not automatically place your window on the top of 
all the other windows on your desktop. To bring it to 
the top, use the WinSetWindowPos service: 


FLAGS~SWP_SHOW + SWP_ACTIVATE + SWP_ZORDER 
SV145-“WinSetWindowPos” FRAME HWND_TOP 0 0 0 0 FLAGS 
_ If you are trying these examples as you read, you 
will see that the client area of the window you just 
created is transparent because you have not yet 
drawn any graphics in it. To make it easier to see the 
effects of your calls to Gpi services, you may want to 
use your mouse to reposition the window now. 

To draw in any window, you need a device con- 
text and a presentation space. A device context is a 
connection to a particular device like a display. A 
presentation space is a virtual coordinate space asso- 
ciated with a device context. You can draw graphics 
and text in a presentation space without worrying 
about device dependencies. Presentation Manager 
manages the conversions from the presentation space 
to the physical device. 

Creating a device context can be quite compli- 
cated, but Presentation Manager provides a very sim- 
ple service that will open a device context that is al- 
ready associated with your window. It is called 
Mipentissiot 

$V145-“WinOpenWindowDC’ CLIENT 
_ (APRC DC CMD)~SV145 
| 





Now you can create a presentation space. To 
make the presentation space easier to ‘work with, you 
can define an arbitrary onda ps The exam- 
ple defines a range of 0 to 100 in oth the X and Y 
directions: Pe STAN 

PSSIZE-SIZEL CAST 1001 1001 


FLAGS-PU_ARBITRARY + GPIA_ASSOC 
| 5V145-"GpiCreatePS” 0 DC PSSIZE FLAGS 
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(APRC PS CMD)-SV145 


The presentation space now exists and you can 
draw on it, but by default, it is mapped to the entire 
display screen. To have your space mapped to the 
client window, you must set the page viewport to 
match the client’s size and position. To do this, query 
the rectangle surrounding the client and set the page 
viewport to match this rectangle: 


RECTANGLE-RECTL CAST 0000 
$V145-“WinQueryWindowRect” CLIENT RECTANGLE 
(APRC OSRC CMD)~SV145 

(API CLIENT RECTANGLE)~CMD 
SVi45-“GpiSetPageViewport” PS RECTANGLE 


Now you're ready to actually draw in your client 
window. You can use all the Gpi services and your 0 
to 1000 coordinate system. Presentation Manager will 
clip and scale your graphics to the client area. 

To start, try setting the color and drawing a box 
that fills the entire client area: 


$V145-“GpiSetColor” PS CLR_BLUE 
POSITION-POINTL CAST 0 0 

SV145-"GpiMove” PS POSITION 

CORNER-POINTL CAST 1000 1000 

SV145-“GpiBox” PS DRO_OUTLINEFILL CORNER 0 0 


Now try changing the color and drawing a 
smaller box with rounded corners: 


SV145-"GpiSetColor” PS CLR_RED 

POSITION-POINTL CAST 100 100 

5V145-“GpiMove’ PS POSITION 

CORNER-POINTL CAST 900 900 

SV145-°GpiBox” PS DRO_OUTLINEFILL CORNER 50 50 


Next, change the color once more and draw some 
text: 
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$V145-"GpiSetColor’ PS CLR_GREEN 
POSITION-POINTL CAST 450 500 
$V145-“GpiMove’ PS POSITION 
SV145-“GpiCharString” PS 11 “Sample Text’ 


Using your presentation space, you can try some 
of the other Gpi services. Gpi€rase, GpiLine, and GpiMarker 
are all useful and easy services you might try. 

As you can see, you can accomplish a lot calling 
OS/2 services interactively. You can create windows 
and experiment with the Presentation Manager ser- 
vices and structures. Eventually, however, you need 
to respond to user input; you need to process 
Presentation Manager messages. Fortunately, this too 
can be done interactively. 


PROCESSING PRESENTATION MANAGER MESSAGES 
AP145 provides several “Apl’ services that are used to 
redirect messages to APL2 for processing. The proce- 
dure is to tell AP145 what messages you want to 
process and then wait for them. 

Your example window needs to respond to three 
events: size, paint, and close. When a size change oc- 
curs, you need to reset your page viewport so your 
coordinate system is mapped to the new window 
size. When part of your window has been invali- 
dated, you need to repaint the invalid area. And 
when the user requests that the window be closed, 





you need to close and destroy it. The following state- 
ments inform AP145 that you want the messages cor- 
responding to these events to be passed to APL2 for 
processing: 


SV145-"AplRegisterMsg” CLIENT WM_PSIZE 0 0 
SV145-"AplRegisterMsg” CLIENT WM_PPAINT 0 0 
SV145~-“AplRegisterMsg” FRAME WM_SYSCOMMAND SC_CLOSE 0 


Once the messages you're interested in have been 
registered, you use the AplWaitMsg service to wait for 
messages. AplWaitMsg updates its four parameters with 
the handle, message identifier, and message parame- 
ters 1 and 2: 


SV145-“AplWaitMsg’ 0 0 0 0 
(APRC OSRC CMD)~SV145 
(SERVICE HANDLE MSG MP1 MP2)~CMD 


The last expression in the previous example will 
extract the window handle, message identifier, and 
the two message parameters from the result returned 
by AP145. You can compare the message identifier 
with any of the standard message identifiers to deter- 
mine which message has been returned. For example, 
the following line of code yields a vector of Boolean 
values, which indicates that the message is a 
WM_SYSCOMMAND message: 


MSG=WM_PSIZE WM_SYSCOMMAND WM_PPAINT 
010 


When you receive a W4_PSIZE message, the size of 
your window has been changed. For your coordinate 
system to continue to work, you should query the 
client window rectangle and set the page viewport 
just as you did initially. 

Presentation Manager sends you a WM_PPAINT mes- 
sage when part of your window has been invalidated 
and needs to be redrawn. This can happen when part 
of your window has been covered and then exposed 
by movement of another window. In response to a 
WM_PPAINT message, you should redraw the invalid 
area and tell Presentation Manager that the invalid 
part of your window is now valid so it does not keep 
sending you WM_PPAINT messages. 

To redraw the graphics, you can simply issue all 
the graphics calls again. Alternatively, you can use 
retained graphics to have the same effect more easily 
and quickly. 

First, set the drawing mode to retained so you 
can draw graphics once and reuse them. 


$V145-°GpiSetDrawingMode” PS DM_DRAWANDRETAIN 
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Now open a segment, redraw your graphics as 
you did before, and then close the segment. When 
using retained graphics, once a segment contains 
graphics, you can draw the segment at any time and 
all the graphics will be redrawn. Following are the 
calls you use to open, close, and draw segments: 


SEGMENT~1 

SV145-“Gpi0penSegment” PS SEGMENT 
SV145-“GpiCloseSegment” PS 
$V145~-“GpiDrawSegment” PS SEGMENT 


Now you're ready to efficiently handle WM_PPAINT 
messages. Here’s some code to query the invalid rec- 
tangle, tell Presentation Manager it’s valid, and draw 
your segment: 


RECTANGLE-RECTL CAST 0000 
$V145-“WinQueryUpdateRect” CLIENT RECTANGLE 
(APRC OSRC CMD)~SV145 

(APT. CLIENT RECTANGLE) ~CMD 
SV145~“WinValidateRect” CLIENT RECTANGLE TRUE 
5V145-°GpiDrawSegment” PS SEGMENT 


Finally, you also need to respond to WM_SYSCOMMAND 
messages. You can verify that the message actually 
corresponds to a close request from the system menu 
by examining the first message parameter. When 
you're done, you can simply destroy your window: 


MP1=SC_CLOSE 
1 
SVi45-"WinDestroyWindow’ FRAME 


When AplWaitMsg returns a message, you can call 
as many Presentation Manager services as you want 
and even continue to interact with your window be- 
fore returning a message result. Messages that are re- 
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ceived while you are processing a message are held 
until the next call to AplWaitMsg. Once you are done 
processing the message, you can use AplReturn to re- 
turn a result or you can use AplWaitMsg to return a re- 
sult and wait for further messages. 


SUMMARY 

In this article you've seen how to build a simple win- 
dow that uses some of the OS/2 Presentation 
Manager’s most sophisticated facilities, including ar- 
bitrary unit presentation spaces and retained graph- 
ics. Using an interactive approach gives you a conve- 
nient way to explore Presentation Manager’s many 
services, and APL2 is an excellent tool to do this. 


David Liebtag, /BM Corp., San Jose, Calif., is an advisory pro- 
grammer in IBM's APL Products and Services group. David's 
recent work has focused on the Presentation Manager facilities 
in the APL2 for OS/2 product. This work has included the session 
manager, editors, printing facilities, and the APL2-PM interface 
processor. David can be reached via Internet at 


hebtag@stlvm20.vnet.ibm.com or CompuServe at 73164,623. 
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library (DLL) that allows REXX command pro- 
cedures to create databases using dBase file for- 
mats. File allocation table (FAT) and High 
Performance File Systems (HPFS) are supported; 
RexxBase uses the REXX application program 
interface. 

American Coders Ltd. Circle No. 151 
Phone; (919) 846-2014 


PowerPak for OS/2. This add-on utility is 
designed to complement O5/2 Warp 3. 
PowerPak has a full-featured program sched- 
uler that enables users to launch various pro- 
grams based on user-defined time intervals. 
The scheduler provides a clock and calendar 
for the OS/2 desktop. PowerPak’s import and 
export facility helps users share data between 
OS /2 applications such as faxes, personal infor- 
mation mangers, and databases. 
Arcadia Technologies Inc. Circle No. 152 
Phone: (818) 446-6945 


Extra! for OS/2. This host connectivity software is 
32 bit, object oriented, multithreaded, and com- 
patible with Warp. Extra! for OS/2 supports 
advanced program-to-program communication 
and a wide range of productivity features, 
including integrated batch file transfer, macros, 
SmartPad, Hotspots, drag-and-drop keyboard, 
and color remappers. 
Attachmate Corp. Circle No. 153 
Phone: (206) 649-6551 


Avista. This fully integrated, multiuser, 
client/server accounting and business manage- 
ment software solution runs on DOS, OS/2, or 
UNIX. Avista is based on a customizable rela- 
tional database specifically designed to aggre- 
gate high-volume transactional data typical to 
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accounting systems. It is aimed to be high per- 
formance and stil cost-effective. 
Avista Software Circle No, 154 
Phone: (404) 564-8015 


BBN Internet Server. This UNIX server has the 
ease of use of BBN’s graphical user interface- 
based software that runs on Apple Macintosh 
or Microsoft Windows desktops. The server 
supports all Internet-protocol client platforms, 
including Windows, Macintosh, UNIX, and 
OS/2. It provides access to widely used 
Internet server functions including World Wide 
Web (WWW) database servers, e-mail, Gopher 
database servers, FTP file retrieval servers, and 
Network News bulletin boards. 


BBN Circle No. 155 
Phone: (800) 632-7638 or (617) 873-8730 


DataLink for Lotus Notes. This is a cost-effec- 
tive, point-and-click solution for migrating and 
synchronizing data between Lotus Notes and 
other major relational databases. DataLink does 
not require scripting or programming. It offers 
complete server-platform independence and 
provides access to data stored in Lotus Notes 
3.0 or higher servers running Windows, OS/2, 
UNIX, or NLM. 
Brainstorm Technologies Circle No, 156 
Phone: (617) 492-3399 


Preditor/2. This graphical, 32-bit editor is 
equipped with the ability to display multiple 
windows, search across multiple files, edit and 
compile simultaneously, and emulate other edi- 
tors. It is customizable—programmers can 
jump to variable declarations, class definitions, 
or start functions. 
Compuware Corp. Circle No. 157 
Phone; (810) 737-7596 
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VisualGen. This application development tool 
for business-critical applications allows pro- 
grammers to develop client and server code 
concurrently for use on workstations and the 
host. Users can take advantage of cooperative 
processing. The company claims its product 
brings new functionality through support for 
Windows clients and C++ application genera- 
tion for OS/? and AIX. 


IBM Circle No. 158 
Phone: (914) 766-1211 


Visual SlickEdit for 0S/2. This programmers’ edi- 
tor offers procedure tagging, multiple clip- 
boards, and compiler error processing. It pro- 
vides the user with a macro language called 
Slick-C as well as a DLL interface for extending 
the editor. Visual SlickEdit supports C/C++, 
Pascal, Fortran, Basic, dBASE, Modula-2, 
assembly language, COBOL, and Ada. 


microEdge Circle No. 159 
Phone: (919) 790-1691 


NOP Pentium Compilers. These compilers 
run under DOS and O5S/2. They are available 
for Fortran, C/C++, and Pascal. They drive 
RISC, CISC, and Vector devices. The new com- 
pilers add Pentium scheduling, the use of 
FXCH instructions to streamline x87 stack 
accesses, and a new peepholer that results in 
smaller code. Other features are dynamic link- 
ing, loop unrolling, numeric register caching, 
and numeric register coloring. 


Microway Circle No. 160 
Phone: (508) 746-7341 


Wizard O.S. 1.0. This multi-operating-system 
boot utility allows users to choose between 
DOS, Windows 95, OS/2, Windows NT, and 
UNIX at boot time. The user can have multiple 
versions of DOS or OS/2 and thus have differ- 
ent configurations of a particular operating sys- 
tem. One hundred different operating systems 
can be installed on the same hard disk. It does 
not require any special disk partitions like Boot 
Manager, nor does it require any disk partition- 
ing or formatting. 


Modular Software 
Systems Circle No. 161 
Phone: (800) 438-3930 or (206) 631-5781 





Quick/2 Install. This installation tool allows the 
entire OS/2 operating system to be installed in 
less than 15 minutes using quarter-inch car- 
tridge backup systems. Quick/2 is ideal for 
users who require the ability to perform several 
installations or who desire an “unattended” 
installation. 


Parallel Storage Solutions Circle No. 162 


(914) 347-7044 


ObjectPro. This is an object-oriented develop- 
ment tool for building robust client/server 
applications. The company announces that ben- 
efits include intuitive modeling, code reuse, 
and productive maintenance that applies to the 
whole business model—business logic as well 
as screens and database interaction, ObjectPro 
supports Oracle and Sybase through native 
interfaces. ODBC drivers are provided that 
support Ingres, SOLBase, DB2/2, Allbase, 
dBase, Access, FoxPro, and 80 on. 
Trinzic Corp. Circle No. 163 
Phone: (617) 891-6500 


GUI-Kit. This C and C++ cross-platform GUI 
development toolkit supports 32-bit develop- 
ment under Win32, Windows NT, O5/2, and 
UNIX/Motif. This object-oriented program- 
ming environment can be used in C or C++. 
Visual Systems Corp. Circle No, 164 
Phone: (612) 434-6382 


The Graham Utilities for OS/2. New utilities are 
added to the already strong suite of over 30 
applications. The user can recover multiple 
deleted files in one step and recover files from 
damaged or unusable High Performance File 
System partitions. Two file defragmenters are 
included. 

Warp Speed Computers Circle No. 165 
Phone: 61 3 384 1060 


Mathematica 2.2. Wolfram Research announces 
the release of a native version of Mathematica 
2.2. The new version takes advantage of OS/2's 
32-bit environment and runs faster. It is com- 
patible with OS/2 Warp 3.0. 


Wolfram Research Inc. 
Phone: (217) 398-0700 


Circle No. 166 
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The staff of OS/2 Developer put together this special section to guide you through the various software 
tools specifically for the performance tuning, testing, and debugging of OS/2 applications. The products 
described in this guide are based on surveys sent to vendors; they are provided as a service to you and 
are free to vendors. These listings do not represent an endorsement by OS/2 Developer. A/though every 
effort has been made to ensure accuracy, we do not assume any responsibility for error or omission in 
this section. 


Testing and Debugging Tools 
Buyer’s Guide 
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AUTOTESTER Circle No. 101 
AutoTester for OS/2 2.02 is an automated testing 
tool designed specifically for OS/2 Program 
Manager applications. AutoTester builds 
structured, object-oriented, and documented 
tests as you operate an application. Thus, the 
user gets a flexible, reusable, and maintain- 
able test library that can be executed unat- 
tended. It supports the skilled developer and 
expert application users. Price: $5,000 per 
copy with quantity discounts. 

AutoTester, 8150 N. Central 
Expressway, Ste. 1300, Dallas, Tex. 75206, 
(800) 328-1196 or (214) 368-1196, fax (214) 
750-9668. 


BON AMI Circle No. 102 
CPU Monitor Plus 2.31 is an OS/2 Performance 
Monitor and Analysis package. It displays 
real-time CPU, RAM, Disk, Interrupt, and 
COM port activity. It will diagnose poorly 
running systems, set execution priorities, 
and log performance data for later analysis. 
It can start, stop, or suspend programs and 
has over 100 different metrics and ratios. 
Price: $129.95. 

Bon Ami, 60 Thoreau St. Ste. 219, 
Concord, Mass. 01742, (508) 371-1997, fax 
(508) 371-2333. 


CARRY ASSOCIATES Circle No. 103 
Sys Maint 3.3 is a 32-bit Presentation Manager 
application that provides a full desktop diag- 
nostic and a backup and repair utility. It iden- 
tifies and fixes a number of common Desktop 


problems, provides a desktop backup and 
restore, allows the user to edit, copy, move, 
backup, search, compare, size, repair, and 
maintain any INI file, including the 
OS2SYS.INI and OS2.INI files. It will view, 
copy, move, split, join, test, compare, and 
maintain extended attributes, including the 
desktop directory structure. Price: 549.95 
plus $7.00 shipping and handling. 

Carry Associates, 990 Ironwood Ct., 
Marco Island, Fla. 33937-4458, (813) 642- 
9126, fax (813) 642-1007. 


CLIENT SERVER 
NETWORKING INC. Circle No. 104 
WATCHIT 2.0 optimizes IBM LAN platforms 
(OS/2, AIX, MVS/VM, and AS/400). 
WATCHIT collects statistics about resource 
and user activity and analyzes the data. It 
automates collection of IBM LAN server 
capacity and performance statistics to help 
improve performance and anticipate capac- 
ity problems. Collection may be automated 
at the server or manually controlled from 
your desktop. Price: $349. 

Client Server Networking Inc., P.O. Box 
370111, West Hartford, Conn., 06137-0111, 
(203) 233-2951, fax (203) 233-2951. 


[BM CORP. Circle No. 105 
Workstation Interactive Test Tool (WITT) 2.2.2 is 
a capture and playback tool for automating 
unit and regression testing. WITT records 
keystrokes, mouse movements, and screen 
images as you step through your application 
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to automatically generate test scripts. WITT 
can also be used to automate many activities 
such as giving demos, entering operator com- 
mands, starting and stopping subsystems, 
system testing, and simulating users for disas- 
ter recovery. WITT installs on the OS/2 desk- 
top and allows testing of Host, OS/2 
Presentation Manager, and Text applications. 

IBM Corp., 555 Bailey Ave., San Jose, 
Calif. 95141, (800) 426-4785 or (408) 463-2000, 
fax (800) 426-4522. 


MERCURY INTERACTIVE CORP. Circle No. 106 
WinRunner for OS/2 is an automated testing 
tool for OS/2 applications that compresses 
manual testing into a single overnight run. It 
tests OS/2 applications in any programming 
language. WinRunner includes automatic 
GUI verifications, inside testing beyond the 
graphical user interface, output synchroniza- 
tion, text recognition, object-oriented record 
and replay, and reusable and portable tests. 
Price: $2,850, 

Mercury Interactive Corp., 470 Portrero 
Ave., Sunnyvale, Calif. 94086, (800) 837-8911 
or (408) 523-9900, fax (408) 523-9911. 


MICROQUILL SOFTWARE 

PUBLISHING INC. Circle No. 107 
SmartHeap 2.2 is a fast (3X-100X), portable, 
reliable ANSI-compliant, and malloc-free 
library. It is thread-safe and supports multi- 
ple memory pools and shared memory. 
SmartHeap provides heap error detection 
and detects bugs other tools miss—leakage, 
overwrites, double-frees, wild pointers, out 
of memory, and references to previously 
freed memory. Price: $695. 

MicroQuill Software Publishing Inc., 
4900 25th Ave. N.E., Ste. 206, Seattle, Wash. 
98105, (800) 441-7822 or (206) 525-8218, fax 
(206) 525-8309. 


PERISCOPE COMPANY INC. Circle No. 108 
Periscope/32 for 0S/2 5.4 is a device driver 
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debugger for OS/2 v. 2.x. This full-screen, 
symbolic, source-level debugger helps devel- 
opers of OS/2 2.0 Base and Presentation 
Manager drivers. It operates at the systems 
level, has easy access to any memory loca- 
tion in the system, and is compatible with 
applications level debuggers. It includes host 
and target system software and a break-out 
switch for crash recovery. 

Periscope Company Inc., 1475 Peachtree 
St., Ste. 100, Atlanta, Ga. 30309, (800) 722- 
7006 or (404) 888-5335, fax (404) 888-5520. 


PROGRAMART CORP. Circle No. 109 
APMPower 2.0 is an OS/2-based product that 
facilitates the analysis of MVS application 
performance data. Operating with 
Programart’s STROBE application perfor- 
mance measurement system, APMPower is 
used to pinpoint and resolve application per- 
formance problems before they enter pro- 
duction. It enables users to freely share 
application performance knowledge, 
improving IS productivity and application 
quality. Price: $2,000 for single user, $4,000 
for current-use licenses. Volume discounts 
available. 

Programart Corp., 124 Mt. Auburn St., 
Cambridge, Mass. 02138, (617) 498-4045, fax 
(617) 868-6069. 


SOFTBRIDGE INC. Circle No. 110 
Automated Test Facility 3.5 tests client/server 
and stand-alone 05/2, Windows, Windows 
NT, and legacy (via 3270 emulation) applica- 
tions. ATF’s two-tiered architecture supports 
true client/server testing. From one central 
point, ATF can run intertwined, simultane- 
ous, unattended tests on multiple PCs, testing 
all client/server layers—graphical user inter- 
faces, distributed applications, and legacy 
systems. Price: $18,000 for base system. 

Softbridge Inc., 125 Cambridge Park Dr., 
Cambridge, Mass. 02140, (800) 955-9190 or 
(617) 576-2257, fax (617) 864-7747. 
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Are you looking for a way to 
manage your production job 
streams? Do you have programs 
that need to run efter the 
completion of one or more other 
programs? Do you want to run 
programs on a regular basis? Do 
you want to process files that 
have just been received from 
another system or modified 
locally? Do you need to take action 
if a file is missing? Do you need to 
| schedule sround holidays and 
periods of heavy CPU load? 

} With ATS you can run your 
programs when YOU want them 
to Pun with out you nang be be 
em a poner 























Version 3.0 
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Take control of your os/e scheduling needs with 


Here are some of the features of 
ATS for 08/2: 

* Manage Production Job 

Streams 

* Programs can be scheduled to 
run anytime. 

* Programs can be dependent 
upon Files, Other Programs, 
Holiday Schedules, and 
External Signals 

* Integrated Operators Console 

* Logging - To File and Console 
New Features: 

* Job Queues - for managing 
your resources while managing 
your tasks 

* Periodic Scheduling 

* COMPLETE API and Command 

Line Interface 
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THE INTELLIGENT 
PROGRAMMER’S 
EDITOR 


s199 
SPECIAL OS/2 
INTROOUCTORY 


OFFER! 


O5/2 
WINDOWS 
WINDOWS NT 
Winners of Software 
Development Productivity Award 


t™ is the high 


soweiad programmer's editor with the speed, 
ease, and features you need to ignite your 
productivity. Learn in no time with our | = 
comprehensive CUA, Brief, Emacs, and VI || | sum 
emulations. Take off with our extensive | | | 
language support, project management, and 


INEW SmartPaste™. 


Powerful features: 
* Incremental search,search and replace 


* Completely configurable 
¢ Spell check comments and strings 


+ Typeless, object-oriented, (-style macro language 


+ Built-in dialog editor 


* Clipboard Inheritance (patent pending) 


AXP machines. 


Cut your work in half using: 
+ Procedure tagging 
+ Syntax color-coding, expansion, and indenting 
+ SmortPaste reindents pasted source code according to 
sis Rib alan: dice dak wala Kati nesting level 
one deemed version & avoiloble for Intel, Mips, and Alpi i Compiler error processing 


To Order, Call 800-93.4-EDIT also (919) 831-0600 or FAX (919) 831-0101 


Vewol SlickEdit, SemartPeste, and Clipboard inheritance are tredemanrks of Minresdge, Windews WI, Mips, end Alpha ure fnodemar ks ef thair respective manuheniurens. 


MicroEdge, Inc. PO Box 18038, Raleigh, NC 27619-8038 USA 
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SOFTOUCH SYSTEMS INC. Circle No. 111 
Gamma Tech Utilities 3.0 for OS/2 Warp 
accelerates disk performance, performs 
High Performance File System (HPFS) 
optimization on line, and defragments 
file allocation table (FAT) files without 
crosslinking their extended attributes. 
Functions include desktop backup, disk 
analysis, boot sector backup, restore, 
and virus protection. Price: $99. 

SofTouch Systems Inc., 1300 5. 
Meridian Ave. Ste. 600, Oklahoma 
City, Okla. 73108, (405) 947-8085, fax 
(405) 632-6537. 


Z500AD SOFTWARE INC. Circle No. 112 
2500AD Simulator/Debugger 5 is a full- 
color, menu-driven debugger. It debugs 
C and assembly language source code. It 
features stack control, memory traps, 
and control of registers, flags, memory, 
and variables. Price: $150. 

2500AD Software Inc., 109 
Brookdale Ave., Buena Vista, Colo. 
81211, (800) 843-8144 or (719) 395-8683, 
fax (719) 395-8206 


VERITAS SOFTWARE CORP. Circle No. 113 
VistaTest supplies the basic tools 
needed to immediately improve detec- 
tion and elimination of latent defects. 
VistalEST provides quick insight into 
what part of mission-critical applica- 
tion code has not been exercised by 
existing test suites. Dynamic coverage 
includes predicate, conditional, block, 
and/or path levels of code coverage. 
The product supports the IBM C Set 2 
and C Set ++ compilers, including tem- 
plates and exception handling. Price: 
VistaTEST (C), $1,800; VistaTEST 
(C/C++), $2,800. 

VistaSIM simulates interface 
behaviors. Using either prepackaged 
OS calls or customized libraries cre- 
ated with the VistaSim Simulation 
Builder, this functionality allows for 
testing of difficult-to-reach code. Price: 
$3,200. 

VistaGRAPH is a general-purpose 
graphing tool that provides presenta- 
tion graphics of charts, line plots, and 
kiviat diagrams. These charts provide 
clear visual representation of test 
results. 

VERITAS Software Corp., 4800 
Great America Parkway, Santa Clara, 
Calif. 95034, (800) 258-8649 or (408) 
727-1222, fax (408) 562-4334. 
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If you're looking for a fully configurable, professional OS/2 PM 
programmer's editor to replace your Current text-mode editor — we 
have what you have been looking for! 


We know changing editors can be a major hassle, You don’t want 

to releam a new set of keystrokes no matter how good the product. 

Well, you don’t have to — we have Brief, CUA, Epsilon, Multi-Ediit, lige or expression 

SlickEdit, PWB, and Borland IDE keyboard mapping waiting for you. If ea>cn and replace 
you're not using one of these, let us know and we will create the IDO Calelahee aie) 
mappings you need. | | 


It has all the features you have come to expect, plus special ge ee ee ae ae | 
features designed to anticipate your needs and increase your see eee led ee a ge. | 
productivity. Features like a ‘C’ source browser that eliminates those ab 
time consuming searches for functions, global variables, typedefs, 

and macros by providing you with instant positioning to both 

definitions and references, Using our powerful "C’ macro language 





you can customize your programming environment to suit your ieee cdiedeccalecutet i ae 
individual needs. retired. Keep up the good work!” - AL. 

RimStar Technology, Inc. Price $299.00 os a 

91 Halls Mill Road Plus Shipping & Handling. nodes ot rocee Rocer their 
Newfields, NH 03856 , T SOEPOCHVO NOKIEEE: So ROKR 
Voice: (603) 778-2500 To order call 1-800-746-7007 ania ea 
Fax: (603) 778-2408 60 day money-back guarantee. © 1994 RimStar Technology inc. 


BBS: (603) 778-4644 . 
Also available for Windows and Windows NT 
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The Suite Way to Build 
Portable Applications 





your job? Then life just 

got easier thanks to the 
zApp* Developer’s Suite 
for Windows. The zApp 
Developer’s Suite is a set of 
highly integrated C++ devel- [ae 
opment tools designed to help (= 
you transform the blueprints [7% 
in your mind into commercial |) 
quality applications—quickly == 
and easily. And best of all, 
applications built using the zApp 
Developer’s Suite are portable to fourteen 
different platforms! 


|: building applications 


The zApp Developer’s Suite consists 
of zApp, the award-winning portable C++ 
application framework; zApp Factory™, a 
fully visual application designer and code 
generator; and the zApp Interface Pack, a 
collection of high-level visual objects for 
the zApp environment. All of these tools 
are highly integrated to provide maximum 
ease of use and flexibility. 


Rapid Application Development. 


Introducing an exciting new visual tech- 
nology that lets you drag and drop a wide 
assortment of objects like toolbars, 
tables, and 3D dialogs; define their char- 
acteristics; and build interfaces of any 





zApp and Inmark are registered trademarks of Inmark 
Development Corporation. zApp Factory is a trademark of 
Inmark Development Corporation. OS/2 is a registered trade- 
mark of IBM. All other trademarks are the property of their 
respective owners. 
In the U.K. and Scandinavia, call PTS/Software Plus 

at +44 (0) 928 579900 
In France, call PTS/Software Plus at (05) 908194 
in Germany, call ESM Software at 07022-9256-0 
In Italy, call Silicon Valley On-Line at (049) 654221 
in Australia, call Micro Way at (03) 580-1333 
BBS; 415-691-9990 « Internet: info@inmark.com 
Commuserve: GO INMARK 
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complexity; all in one powerful but easy 
to use environment. With the click of a 
button, you can engage a powerful test 
mode which lets you interact with your 
application, seeing it exactly like your 
end user will see it: letting you fill in 
dialogs, pull down menus, etc. When you 
are pleased with the look and feel of your 
application, fully commented C++ source 
code is only a mouse click away, thanks 
to the zApp Developer’s Suite’s code gen- 
eration capabilities. 


Object-oriented Power. 


The best news is that this development 
environment sits on top of zApp, the 
industry leading C++ application frame- 
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} work, and the zApp Interface 
Pack, so you have all of their power 
at your disposal — toolbars, table 
objects, advanced graphics — in 

all, over 300 object classes of power 
J just waiting to be tomorrow’s best- 
selling application. 


Portability and More. 


When you’re done building your 
application, then you can decide 
what platforms you want to support! 
Applications built using the zApp 
Developer's Suite are single-source portable 
to fourteen different platforms. By simply 
recompiling, your application will run 
natively on Windows, Win32 (Windows 
NT, Windows 95, and NT on the DEC 
Alpha), OS/2*, DOS Text, DOS Graphics 
and seven X/Motif platforms: IBM 
RS/6000 AIX, HP HPUX 9.x, SGI IRIX 
5.2, SCO UNIX, Sun Solaris 2.x, Sun 
SunOS 4.1.x, Sun Solaris x86. 


Free Demo. 


Sound impossible? Well, if seeing is 
believing for you, call 1-800-346-6275, ask 
for our free demo disk, and get a glimpse 
of what the future has to offer. 


INMARK 


2065 Landings Drive, Mountain View, CA 94043 
T: 800-346-6275 or 415-691-9000 F; 415-691-9099 


6362-8001-e27 











